llms-full.txt

# Archgate CLI

> Archgate is a CLI tool for AI governance via Architecture Decision Records (ADRs). It combines human-readable documentation with machine-checkable TypeScript rules to enforce architectural decisions across codebases — for both humans and AI agents.

Archgate lets teams write an ADR once and enforce it everywhere. ADRs are Markdown files with YAML frontmatter that describe architectural decisions. Companion `.rules.ts` files contain automated TypeScript checks that run against the codebase and report violations with file paths and line numbers.

## Key capabilities

- **Executable rules**: Write compliance rules in TypeScript. Archgate runs them against your codebase and reports violations with file paths and line numbers.
- **CI integration**: Wire `archgate check` into any CI/CD pipeline. Exit code 1 blocks merges when rules are violated.
- **AI-aware governance**: Editor plugins give AI agents (Claude, Cursor, Copilot) live access to ADRs. Agents read decisions before writing code and validate after.
- **Editor plugins**: Claude Code, VS Code, Cursor, and Copilot CLI plugins give AI agents role-based governance skills.
- **Self-governance**: Archgate governs its own development using the same tool.

## Installation

Install standalone (no Node.js required): `curl -fsSL https://raw.githubusercontent.com/archgate/cli/main/install.sh | sh` (macOS/Linux) or `irm https://raw.githubusercontent.com/archgate/cli/main/install.ps1 | iex` (Windows PowerShell). Also available via npm (`npm install -g archgate`) or direct download from GitHub Releases.

## Documentation

- [Getting Started — Installation](https://cli.archgate.dev/getting-started/installation/): Install on macOS, Linux, or Windows via npm, Homebrew, or standalone binary.
- [Getting Started — Quick Start](https://cli.archgate.dev/getting-started/quick-start/): Set up Archgate in under 5 minutes with your first ADR and rule.
- [Core Concepts — ADRs](https://cli.archgate.dev/concepts/adrs/): How Architecture Decision Records work as both documentation and executable rules.
- [Core Concepts — Rules](https://cli.archgate.dev/concepts/rules/): The TypeScript rule system that turns ADR decisions into automated compliance checks.
- [Core Concepts — Domains](https://cli.archgate.dev/concepts/domains/): Organize ADRs by domain for targeted governance.
- [Guide — Writing ADRs](https://cli.archgate.dev/guides/writing-adrs/): Complete guide to writing effective ADRs with YAML frontmatter and markdown structure.
- [Guide — Writing Rules](https://cli.archgate.dev/guides/writing-rules/): Write TypeScript rules using the satisfies RuleSet pattern with file matching and violation reporting.
- [Guide — CI Integration](https://cli.archgate.dev/guides/ci-integration/): Add Archgate checks to GitHub Actions, GitLab CI, or any pipeline.
- [Guide — Claude Code Plugin](https://cli.archgate.dev/guides/claude-code-plugin/): Give AI agents a governance workflow that reads ADRs, validates code, and captures patterns.
- [Guide — VS Code Plugin](https://cli.archgate.dev/guides/vscode-plugin/): Real-time ADR compliance in VS Code.
- [Guide — Copilot CLI Plugin](https://cli.archgate.dev/guides/copilot-cli-plugin/): Add architecture governance to GitHub Copilot CLI.
- [Guide — Cursor Integration](https://cli.archgate.dev/guides/cursor-integration/): Configure Cursor IDE with Archgate agent rules and skills.
- [Guide — Pre-commit Hooks](https://cli.archgate.dev/guides/pre-commit-hooks/): Automatically check ADR compliance before every commit.
- [Reference — CLI Commands](https://cli.archgate.dev/reference/cli-commands/): Complete reference for init, check, adr create/list/show, login, and more.
- [Reference — Rule API](https://cli.archgate.dev/reference/rule-api/): TypeScript API reference for RuleSet with satisfies, RuleContext, and violation reporting.
- [Reference — ADR Schema](https://cli.archgate.dev/reference/adr-schema/): YAML frontmatter schema and markdown structure reference for ADRs.
- [Examples — Common Rule Patterns](https://cli.archgate.dev/examples/common-rule-patterns/): Ready-to-use rule patterns for naming conventions, import restrictions, and more.

## Full documentation

For the complete documentation in a single file, see [llms-full.txt](https://cli.archgate.dev/llms-full.txt).

## Optional

- [GitHub Repository](https://github.com/archgate/cli)
- [Editor Plugin Beta](https://plugins.archgate.dev)
- [npm Package](https://www.npmjs.com/package/archgate)

---

# Full documentation

Below is the complete English documentation for Archgate CLI.

## Archgate

Source: https://cli.archgate.dev/

## 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.

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

  
    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.
  
  
    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.
  
  
    Editor plugins give AI agents direct access to your ADRs via CLI commands.
    They read decisions before writing code and validate after. No copy-pasting
    rules into prompts.
  
  
    Archgate governs its own development. The same tool that checks your code
    checks ours. Our own ADRs enforce command structure, error handling, output
    formatting, testing, and more — [see them on
    GitHub](https://github.com/archgate/cli/tree/main/.archgate/adrs).
  

## Editor plugins

The Archgate CLI works standalone, but **editor plugins** unlock a full AI guardrails 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.

  
    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.
  
  
    The Cursor plugin provides pre-built agent rules and skills that give
    Cursor's AI agent the same guardrails workflow as Claude Code.
  

Editor plugins are currently in beta. Run `archgate login` to sign up and authenticate, then `archgate init --install-plugin` to set up the plugin.

## Learn more

---

## Getting Started: Installation

Source: https://cli.archgate.dev/getting-started/installation/

## Install standalone (recommended)

The fastest way to install Archgate — no Node.js or package manager required:

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

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

# Windows (Git Bash / MSYS2)
curl -fsSL https://cli.archgate.dev/install-unix | sh
```

This downloads a pre-built binary for your platform and installs it to `~/.archgate/bin/`. The installer detects your shell profiles and offers to add the directory to your PATH.

On Windows, the PowerShell installer also detects Git Bash shell profiles (`.bashrc`, `.bash_profile`, `.profile`) and offers to configure PATH there as well.

You can customize the install with environment variables:

| Variable               | Description                                 | Default           |
| ---------------------- | ------------------------------------------- | ----------------- |
| `ARCHGATE_VERSION`     | Install a specific version (e.g. `v0.11.2`) | Latest release    |
| `ARCHGATE_INSTALL_DIR` | Custom install directory                    | `~/.archgate/bin` |

You can also download binaries directly from [GitHub Releases](https://github.com/archgate/cli/releases).

## Install via npm

Install Archgate globally using your preferred Node.js package manager:

```bash
# npm
npm install -g archgate

# Bun
bun install -g archgate

# Yarn
yarn global add archgate

# pnpm
pnpm add -g archgate
```

This installs a lightweight wrapper that delegates to a platform-specific binary. The CLI itself is a standalone binary compiled with Bun — Node.js is only needed for the npm/yarn/pnpm wrapper.

## Install as a dev dependency

You can also add Archgate as a dev dependency in your project and run it through your package manager's script runner. This is useful for pinning a specific version per project or running checks in CI without a global install.

```bash
# npm
npm install -D archgate

# Bun
bun add -d archgate

# Yarn
yarn add -D archgate

# pnpm
pnpm add -D archgate
```

Then run Archgate via your package manager:

```bash
# npm / Yarn / pnpm
npx archgate check

# Bun
bun run archgate check
```

Or add a script to your `package.json`:

```json
{ "scripts": { "check:adrs": "archgate check" } }
```

```bash
# Works with any package manager
npm run check:adrs
bun run check:adrs
yarn check:adrs
pnpm check:adrs
```

## Install via pip (Python)

Install Archgate globally using pip or pipx:

```bash
# pip
pip install archgate

# pipx (recommended for CLI tools)
pipx install archgate
```

This installs a lightweight Python wrapper that delegates to a platform-specific binary. Python 3.8+ is required.

## Install via dotnet

Install Archgate as a .NET global tool:

```bash
dotnet tool install -g archgate
```

Requires .NET 8.0+ SDK. The tool downloads the platform binary on first run.

## Install via Go

Install Archgate using `go install`:

```bash
go install github.com/archgate/cli/shims/go/cmd/archgate@latest
```

Requires Go 1.21+. The compiled Go wrapper downloads the platform binary on first run.

## Install via RubyGems

Install Archgate as a Ruby gem:

```bash
gem install archgate
```

Requires Ruby 2.7+. The gem downloads the platform binary on first run.

## Install via Maven / jbang (Java)

Install Archgate using jbang:

```bash
jbang app install archgate@dev.archgate
```

Or download the executable JAR from Maven Central (`dev.archgate:archgate-cli`) and run directly:

```bash
java -jar archgate-cli-0.39.0.jar check
```

Requires Java 11+. The shim downloads the platform binary on first run.

## Platform support

Archgate ships pre-built binaries for the following platforms:

| Platform | Architecture | Artifact                |
| -------- | ------------ | ----------------------- |
| macOS    | arm64        | `archgate-darwin-arm64` |
| Linux    | x86_64       | `archgate-linux-x64`    |
| Windows  | x86_64       | `archgate-win32-x64`    |

The correct binary is downloaded automatically from GitHub Releases on first run and cached to `~/.archgate/bin/`.

## Verify installation

```bash
archgate --version
```

You should see the installed version printed to stdout.

## Install via proto

If you use [proto](https://moonrepo.dev/proto) (moonrepo's toolchain manager), you can install Archgate directly as a proto plugin — no Node.js or npm required.

Add the plugin to your `.prototools`:

```toml
[plugins.tools]
archgate = "github://archgate/proto-plugin"
```

Then install and use it like any other proto tool:

```bash
proto install archgate
archgate check
```

Proto manages the binary for you, including version pinning and auto-installation. To pin a specific version, add it at the root of `.prototools`:

```toml
archgate = "0.15.0"

[plugins.tools]
archgate = "github://archgate/proto-plugin"
```

You can also list available versions and manage installations with proto commands:

```bash
proto list-remote archgate   # list available versions
proto install archgate 0.15.0  # install a specific version
proto pin archgate 0.15.0      # pin version in .prototools
```

If you prefer `npm install -g archgate` instead of the proto plugin, you need to configure proto to expose global npm binaries. Add `shared-globals-dir = true` under `[tools.npm]` in `~/.proto/config.toml`, then add `$HOME/.proto/tools/node/globals/bin` to your shell PATH.

## Next steps

Once installed, run `archgate init` in your project to set up linting and guardrails. See the [Quick Start](/getting-started/quick-start/) guide for a walkthrough.

Want your AI agent to read ADRs before coding and validate after? The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) add a full guardrails workflow on top of the CLI. Run `archgate login` to sign up and get started.

---

## Getting Started: Quick Start

Source: https://cli.archgate.dev/getting-started/quick-start/

## 1. Install Archgate

If you have not installed the CLI yet:

```bash
# Standalone (no Node.js required)
curl -fsSL https://cli.archgate.dev/install-unix | sh

# Or via npm
npm install -g archgate
```

See the [Installation](/getting-started/installation/) page for all options, including Windows and custom install directories.

## 2. Initialize your project

Navigate to your project root and run the `init` command:

```bash
cd my-project
archgate init
```

This creates the `.archgate/` directory with the following structure:

```
.archgate/
  adrs/
    ARCH-001-example.md          # Example ADR
    ARCH-001-example.rules.ts    # Example rules file
  lint/
    archgate.config.ts           # Archgate configuration
```

The generated files give you a working example to build on.

## 3. Edit the example ADR

Open `.archgate/adrs/ARCH-001-example.md`. Every ADR starts with YAML frontmatter that defines its identity:

```yaml
---
id: ARCH-001
title: Example Decision
domain: architecture
rules: true
files: ["src/**/*.ts"]
---
```

- **id** — Unique identifier. Convention is `ARCH-NNN` but any string works.
- **title** — Human-readable name for the decision.
- **domain** — Groups related ADRs together (`architecture`, `backend`, `frontend`, `data`, or `general`).
- **rules** — Set to `true` if this ADR has a companion `.rules.ts` file with automated checks.
- **files** — Optional glob patterns that scope which files the rules apply to.

Below the frontmatter, write the decision in markdown. Archgate does not enforce a specific section structure, but the recommended sections are: Context, Decision, Do's and Don'ts, Consequences, Compliance, and References.

## 4. Add a companion rules file

Create a `.rules.ts` file next to your ADR with the same name prefix. Rules are written in TypeScript using the `RuleSet` type:

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "no-console-error": {
      description: "Use logError() instead of console.error()",
      async check(ctx) {
        for (const file of ctx.scopedFiles) {
          const matches = await ctx.grep(file, /console\.error\(/);
          for (const match of matches) {
            ctx.report.violation({
              message: "Use logError() instead of console.error()",
              file: match.file,
              line: match.line,
              fix: "Import logError from your helpers and use it instead",
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

Each rule has a unique key, a description, and an async `check` function. Inside `check`, you have access to:

- **`ctx.scopedFiles`** — Files matching the ADR's `files` glob patterns.
- **`ctx.grep(file, pattern)`** — Search a file for regex matches, returning file paths and line numbers.
- **`ctx.report.violation()`** — Report a violation with a message, file path, line number, and optional fix suggestion.

## 5. Run checks

Run the compliance checker against your codebase:

```bash
archgate check
```

Archgate loads every ADR with `rules: true`, executes its companion rules file, and prints results. The exit code tells you the outcome:

| Exit code | Meaning                                       |
| --------- | --------------------------------------------- |
| 0         | All rules pass. No violations found.          |
| 1         | One or more violations detected.              |
| 2         | Internal error (e.g., malformed ADR or rule). |

To check only staged files (useful in pre-commit hooks or CI):

```bash
archgate check --staged
```

## What's next?

Now that you have a working setup, dive deeper:

**Understand the concepts:**

- [ADRs](/concepts/adrs/) — What Architecture Decision Records are and how Archgate uses them.
- [Rules](/concepts/rules/) — How companion `.rules.ts` files turn decisions into automated checks.
- [Domains](/concepts/domains/) — How domains group related ADRs and scope file matching.

**Write your own:**

- [Writing ADRs](/guides/writing-adrs/) — Learn the full ADR format and best practices for writing effective decisions.
- [Writing Rules](/guides/writing-rules/) — Explore the rule API, advanced patterns, and how to test your rules.
- [Common Rule Patterns](/examples/common-rule-patterns/) — Copy-pasteable patterns for dependency checks, naming conventions, and more.

**Integrate into your workflow:**

- [CI Integration](/guides/ci-integration/) — Wire `archgate check` into GitHub Actions, GitLab CI, or any pipeline.
- [Pre-commit Hooks](/guides/pre-commit-hooks/) — Run checks locally before every commit.
- [Claude Code Plugin](/guides/claude-code-plugin/) — Give AI agents architecture-aware guardrails with role-based skills.
- [Cursor Integration](/guides/cursor-integration/) — Use Archgate with Cursor IDE for AI-assisted development.

Want AI agents that automatically read your ADRs before coding? Run `archgate login` to sign up and authenticate, then run `archgate init --install-plugin` to set up the plugin.

---

## Core Concepts: Architecture Decision Records

Source: https://cli.archgate.dev/concepts/adrs/

An Architecture Decision Record (ADR) is a short document that captures a single architectural decision along with its context and consequences. ADRs answer the question: _why_ was this decision made, and _what_ are its trade-offs?

Archgate builds on the ADR concept by giving each decision two expressions: a **document** that humans and AI agents read, and an optional **rules file** that machines execute.

## Two Expressions of an ADR

### ADR as Document

The document is a Markdown file with YAML frontmatter stored in `.archgate/adrs/`. It describes the decision in plain language: what problem it solves, what alternatives were considered, what the team decided, and what consequences follow.

Both humans and AI agents consume this document. When an AI coding agent is about to write code, it reads the relevant ADRs to understand the constraints before generating anything.

With the [Claude Code](/guides/claude-code-plugin/) or [Cursor](/guides/cursor-integration/) plugin, your AI agent reads the applicable ADRs automatically before every coding task -- no manual copy-pasting into prompts. [Sign up for beta access](https://plugins.archgate.dev).

### ADR as Rules

The rules file is a companion `.rules.ts` file that exports a plain object typed with `satisfies RuleSet`. When you run `archgate check`, the CLI loads every ADR that has `rules: true` in its frontmatter, executes the companion rules file against your codebase, and reports any violations with file paths and line numbers.

Not every ADR needs rules. Some decisions are best enforced through code review alone. Set `rules: false` when no automated check is practical.

## File Naming Convention

ADR files follow a strict naming convention that encodes the domain prefix, sequence number, and a human-readable slug:

```
{PREFIX}-{NNN}-{slug}.md            # The document
{PREFIX}-{NNN}-{slug}.rules.ts      # The companion rules file (optional)
```

For example, an architecture-domain ADR about command structure would produce:

```
ARCH-001-command-structure.md
ARCH-001-command-structure.rules.ts
```

The prefix comes from the ADR's domain (see [Domains](/concepts/domains/)). The sequence number is zero-padded to three digits and auto-incremented by `archgate adr create`.

## YAML Frontmatter

Every ADR document starts with a YAML frontmatter block between `---` delimiters. The frontmatter is the machine-readable metadata that Archgate uses to load, filter, and scope rules.

| Field              | Type         | Required | Description                                                                                                                                                                                  |
| ------------------ | ------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | string       | Yes      | Unique identifier like `ARCH-001` or `BE-003`                                                                                                                                                |
| `title`            | string       | Yes      | Human-readable title of the decision                                                                                                                                                         |
| `domain`           | string       | Yes      | Registered domain name. Built-ins: `backend`, `frontend`, `data`, `architecture`, `general`. [Custom domains](/concepts/domains/#custom-domains) can be added via `archgate adr domain add`. |
| `rules`            | boolean      | Yes      | Whether this ADR has a companion `.rules.ts` file                                                                                                                                            |
| `files`            | string array | No       | Glob patterns that scope which files the rules check                                                                                                                                         |
| `respectGitignore` | boolean      | No       | Whether to filter out `.gitignore`d files. Defaults to `true`.                                                                                                                               |

The `files` field is optional. When present, it restricts rule execution to only the files matching the given globs. When absent, rules run against all project files. For example, `files: ["src/commands/**/*.ts"]` limits checks to command files only.

The `respectGitignore` field is also optional. By default, files listed in `.gitignore` are excluded from all file-scanning operations (`ctx.scopedFiles`, `ctx.glob()`, `ctx.grepFiles()`). Set `respectGitignore: false` to include gitignored files -- useful for rules that need to inspect build output or generated files.

## ADR Body Sections

After the frontmatter, the ADR body follows a standard section structure:

### Context

Describes the problem or situation that prompted the decision. Include alternatives that were considered and why they were rejected.

### Decision

States the decision itself and its key constraints. This is the section AI agents pay the most attention to when deciding how to write code.

### Do's and Don'ts

Concrete, actionable guidance split into two sub-sections. These act as a quick-reference checklist for developers and AI agents.

### Consequences

Split into three sub-sections:

- **Positive** -- benefits the decision provides
- **Negative** -- trade-offs accepted
- **Risks** -- things that could go wrong and how to mitigate them

### Compliance and Enforcement

Describes how the decision is enforced, both through automated rules (with rule IDs and severities) and manual review checklists.

### References

Links to related ADRs, external documentation, or design documents.

## Complete Example

Below is a full ADR with frontmatter and all sections filled in.

```markdown
---
id: BE-001
title: API Response Envelope
domain: backend
rules: true
files: ["src/api/**/*.ts"]
---

## Context

The API returns data in inconsistent shapes across endpoints. Some endpoints
wrap responses in `{ data, error }`, others return raw arrays, and error
responses vary between plain strings and structured objects.

**Alternatives considered:**

- **No envelope** -- Return raw data and rely on HTTP status codes alone.
  Simple, but clients cannot distinguish between "the endpoint returned an
  empty array" and "the endpoint errored."
- **GraphQL-style errors array** -- Use `{ data, errors: [] }`. Flexible
  but adds complexity for simple REST endpoints.

The chosen envelope balances consistency with simplicity.

## Decision

All API endpoints MUST return responses in a standard envelope:

- Success: `{ data: T }`
- Error: `{ error: { code: string, message: string } }`

HTTP status codes remain the primary success/failure signal. The envelope
provides a predictable structure for clients to parse.

## Do's and Don'ts

### Do

- Wrap all API responses in the `{ data }` or `{ error }` envelope
- Use specific error codes (e.g., `VALIDATION_FAILED`, `NOT_FOUND`)
- Include the HTTP status code that matches the error semantics

### Don't

- Don't return raw arrays or primitives from API endpoints
- Don't nest envelopes (no `{ data: { data: ... } }`)
- Don't put stack traces in the error message field

## Consequences

### Positive

- Clients can parse every response with the same logic
- Error responses always have a machine-readable code for programmatic handling

### Negative

- Adds a small amount of boilerplate to every endpoint handler
- Slightly larger payloads due to the wrapper object

### Risks

- Developers may forget the envelope on new endpoints. Mitigated by
  the automated rule that scans for non-conforming return statements.

## Compliance and Enforcement

### Automated Enforcement

- **Archgate rule** BE-001/response-envelope: Scans API handler files for
  return statements and verifies they use the envelope helper. Severity: error.

### Manual Enforcement

Code reviewers MUST verify:

1. New API endpoints use the response envelope
2. Error responses include a specific error code, not a generic message

## References

- [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines)
- [ARCH-002 -- Error Handling](./ARCH-002-error-handling.md)
```

---

## Core Concepts: Domains

Source: https://cli.archgate.dev/concepts/domains/

Domains are categories that group related ADRs together. Every ADR belongs to exactly one domain, and the domain determines the prefix used in the ADR's identifier.

## Built-in Domains

Archgate ships with five built-in domains. Each has a short prefix that appears at the start of every ADR ID in that domain.

| Domain         | Prefix | Use for                                             |
| -------------- | ------ | --------------------------------------------------- |
| `backend`      | `BE`   | Server-side logic, APIs, databases, services        |
| `frontend`     | `FE`   | UI components, client-side logic, styling patterns  |
| `data`         | `DATA` | Data models, schemas, pipelines, storage strategies |
| `architecture` | `ARCH` | Cross-cutting architectural decisions               |
| `general`      | `GEN`  | General project conventions and workflows           |

For example, the third backend ADR would have the ID `BE-003`, and a first frontend ADR would be `FE-001`.

## How Domains Are Used

### ADR Identification

The domain prefix is baked into every ADR's `id` field. When you run `archgate adr create` and select a domain, the CLI automatically determines the next available sequence number for that domain's prefix. An architecture domain with two existing ADRs (`ARCH-001`, `ARCH-002`) would assign `ARCH-003` to the next one.

The file name mirrors the ID:

```
ARCH-003-dependency-policy.md
ARCH-003-dependency-policy.rules.ts
```

### Filtering

The `archgate adr list` command supports a `--domain` flag to show only ADRs from a specific domain:

```bash
archgate adr list --domain backend
archgate adr list --domain architecture
```

This is useful in large projects where dozens of ADRs span multiple concerns. Filtering by domain lets you focus on the decisions relevant to your current work.

### AI Agent Context

The `archgate review-context` command groups changed files by domain when providing context to AI agents. When an agent is about to write code, it receives only the ADR briefings relevant to the domains its changes touch, rather than the full set of all ADRs. This scoping reduces noise and helps agents focus on the constraints that actually apply.

### Scoped Validation

While domains themselves do not restrict which files a rule can check (that is the job of the `files` glob in the ADR frontmatter), domains provide a logical grouping that helps teams organize their governance. A backend team can review all `BE-*` ADRs to understand their constraints, while the frontend team focuses on `FE-*`.

## When to Use Which Domain

### backend

Use for decisions about server-side code: API design patterns, database access conventions, authentication flows, service-to-service communication, queue handling, and background job patterns.

**Example ADRs:** API response envelope format, database migration strategy, error code taxonomy.

### frontend

Use for decisions about client-side code: component structure, state management patterns, styling approaches, accessibility requirements, and build tooling choices.

**Example ADRs:** Component file structure, CSS methodology, form validation pattern.

### data

Use for decisions about data: schema design, data pipeline conventions, storage engine choices, serialization formats, and data validation strategies.

**Example ADRs:** Event schema versioning, database naming conventions, data retention policy.

### architecture

Use for cross-cutting decisions that span multiple domains or affect the project's overall structure. These are decisions that backend, frontend, and data teams all need to follow.

**Example ADRs:** Command structure, error handling conventions, dependency management policy, testing standards.

### general

Use for project-wide conventions that do not fit neatly into a technical domain: code review processes, commit message formats, documentation standards, and onboarding practices.

**Example ADRs:** Commit message format, PR description template, documentation requirements.

## Choosing the Right Domain

When deciding which domain an ADR belongs to, consider who needs to follow it:

- If only backend developers need to follow it, use `backend`.
- If only frontend developers need to follow it, use `frontend`.
- If it concerns data modeling or pipelines specifically, use `data`.
- If it applies across multiple technical domains, use `architecture`.
- If it is a process or convention rather than a technical decision, use `general`.

When in doubt between `architecture` and a specific domain, prefer the more specific domain. Reserve `architecture` for decisions that genuinely cut across boundaries.

## Custom Domains

When the built-in five are a genuine mismatch for a category of decisions — for example, `security`, `ml-ops`, or `compliance` — you can register a custom domain via the CLI:

```bash
# See what's currently recognised in this project
archgate adr domain list

# Register a new domain with its ID prefix
archgate adr domain add security SEC

# Remove a custom domain (built-ins cannot be removed)
archgate adr domain remove security
```

Custom domain-to-prefix mappings persist in [`.archgate/config.json`](/reference/configuration/) and are merged with the built-ins at read time. A registered custom domain behaves exactly like a built-in: `archgate adr create --domain security` auto-generates IDs like `SEC-001`, and `archgate adr list --domain security` filters to those ADRs.

### Naming rules

- **Name** — lowercase kebab-case, 2–32 characters (e.g., `security`, `ml-ops`, `compliance`).
- **Prefix** — uppercase letters, digits, or underscores, 2–10 characters (e.g., `SEC`, `MLOPS`, `COMP`).
- Custom names and prefixes cannot collide with built-ins or any other custom entry.

### When to prefer a built-in

The built-in five are deliberately opinionated. Before registering a custom domain, check whether the decision can be folded under an existing one:

- A decision about auth middleware usually fits under `backend`, even if the motivation is security.
- A decision about schema versioning usually fits under `data`, even if the motivation is compliance.
- A decision that spans multiple technical areas usually fits under `architecture`.

Reach for a custom domain only when none of the built-ins is a genuine fit — for example, when you have a dedicated team or compliance regime that needs its own governance surface.

### AI agent guidance

When using the Archgate editor plugin to author ADRs, agents are instructed to default to the built-in domains and to ask before introducing a custom one. They'll surface the merged list via `archgate adr domain list` and only register a new domain after confirming with you that no built-in fits.

---

## Core Concepts: Rules

Source: https://cli.archgate.dev/concepts/rules/

Rules are the executable side of an ADR. They live in companion `.rules.ts` files alongside the ADR document and export a plain object typed with `satisfies RuleSet`. When you run `archgate check`, the CLI loads each ADR that has `rules: true`, imports its companion rules file, and executes every check against your codebase.

## Defining Rules

A rules file is a TypeScript module that default-exports a plain object conforming to the `RuleSet` type. The type is provided by the local shim auto-generated by `archgate init` (no npm install needed):

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "rule-key": {
      description: "What this rule checks",
      severity: "error",
      async check(ctx) {
        // Inspect files and report violations
      },
    },
  },
} satisfies RuleSet;
```

Each key in the `rules` object becomes the rule ID. The full rule identifier shown in check output combines the ADR ID and the rule key, for example `ARCH-004/no-barrel-files`.

## Rule Structure

Every rule has three parts:

| Property      | Type     | Required | Description                                   |
| ------------- | -------- | -------- | --------------------------------------------- |
| `description` | string   | Yes      | A short summary of what the rule checks       |
| `severity`    | string   | No       | `"error"` (default), `"warning"`, or `"info"` |
| `check`       | function | Yes      | Async function receiving a `RuleContext`      |

### Severity Levels

Severity determines what happens when a rule finds a problem:

| Severity  | Exit Code | Effect                                    |
| --------- | --------- | ----------------------------------------- |
| `error`   | 1         | Violation is reported and the check fails |
| `warning` | 0         | Warning is logged but the check passes    |
| `info`    | 0         | Informational message, check passes       |

When `archgate check` runs, exit code 1 means at least one `error`-severity violation was found. Exit code 0 means no errors (warnings and info messages are logged but do not block).

## The RuleContext

The `check` function receives a `RuleContext` object that provides everything a rule needs to inspect the codebase and report findings.

### Project Information

| Property           | Type       | Description                                                                         |
| ------------------ | ---------- | ----------------------------------------------------------------------------------- |
| `ctx.projectRoot`  | `string`   | Absolute path to the project root directory                                         |
| `ctx.scopedFiles`  | `string[]` | Files matching the ADR's `files` globs, or all project files if no globs are set    |
| `ctx.changedFiles` | `string[]` | Files changed in git (branch diff plus uncommitted changes, or `--staged`/`--base`) |

### File Operations

| Method               | Returns             | Description                        |
| -------------------- | ------------------- | ---------------------------------- |
| `ctx.glob(pattern)`  | `Promise<string[]>` | Find files matching a glob pattern |
| `ctx.readFile(path)` | `Promise<string>`   | Read a file's content as a string  |
| `ctx.readJSON(path)` | `Promise<unknown>`  | Read and parse a JSON file         |

### Search Operations

| Method                             | Returns                | Description                                  |
| ---------------------------------- | ---------------------- | -------------------------------------------- |
| `ctx.grep(file, pattern)`          | `Promise` | Search a single file with a regex pattern    |
| `ctx.grepFiles(pattern, fileGlob)` | `Promise` | Search across multiple files matching a glob |

Both `grep` and `grepFiles` return an array of `GrepMatch` objects:

```typescript
interface GrepMatch {
  file: string; // Relative path from project root
  line: number; // 1-based line number
  column: number; // 1-based column number
  content: string; // The full line content
}
```

### Reporting

The `ctx.report` object provides three methods for reporting findings:

```typescript
ctx.report.violation({ message, file?, line?, fix? });
ctx.report.warning({ message, file?, line?, fix? });
ctx.report.info({ message, file?, line?, fix? });
```

Each method accepts an object with:

| Property  | Type   | Required | Description                          |
| --------- | ------ | -------- | ------------------------------------ |
| `message` | string | Yes      | What the problem is                  |
| `file`    | string | No       | Relative path to the offending file  |
| `line`    | number | No       | Line number where the problem occurs |
| `fix`     | string | No       | Suggested fix for the violation      |

Use `ctx.report.violation()` for problems that must block merges. Use `ctx.report.warning()` for issues worth flagging but not blocking. Use `ctx.report.info()` for purely informational output.

## Rule Timeout

Each rule has a 30-second execution timeout. If a rule's `check` function does not complete within 30 seconds, it is terminated and reported as an error. This prevents runaway rules from blocking the pipeline indefinitely.

## Complete Example

Here is a complete rules file that checks for a banned import pattern. It enforces that no source file imports directly from `node:fs` (the project requires using a wrapper instead).

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "no-direct-fs-import": {
      description:
        "Source files must not import directly from node:fs; use the fs wrapper",
      severity: "error",
      async check(ctx) {
        const sourceFiles = ctx.scopedFiles.filter(
          (f) => f.endsWith(".ts") && !f.endsWith(".test.ts")
        );

        for (const file of sourceFiles) {
          const matches = await ctx.grep(file, /from ["']node:fs["']/);

          for (const match of matches) {
            ctx.report.violation({
              message: `Direct import from "node:fs" is not allowed. Use the fs wrapper from "src/helpers/fs" instead.`,
              file: match.file,
              line: match.line,
              fix: 'Replace the import with: import { readFile, writeFile } from "../helpers/fs"',
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

When this rule runs against a file containing `import { readFileSync } from "node:fs"`, the output looks like:

```
ARCH-007/no-direct-fs-import  ERROR
  src/services/config.ts:3 — Direct import from "node:fs" is not allowed. Use the fs wrapper from "src/helpers/fs" instead.
  Fix: Replace the import with: import { readFile, writeFile } from "../helpers/fs"
```

## Execution Model

Rules execute with the following guarantees:

- **Parallel across ADRs** -- Rules from different ADRs run concurrently for faster execution.
- **Sequential within an ADR** -- Rules belonging to the same ADR run one after another, so earlier rules can establish context for later ones.
- **Scoped files are pre-resolved** -- The `ctx.scopedFiles` array is populated before your `check` function is called, based on the ADR's `files` globs.
- **Changed files auto-detected** -- `ctx.changedFiles` is automatically populated with the branch diff against the base branch (e.g., `main`) plus uncommitted working-tree changes (staged, unstaged, and untracked non-ignored files). Use `--staged` for pre-commit hooks (staged files only) or `--base <ref>` for an explicit base. This enables cross-file dependency rules to work locally, not just in CI.

The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) run `archgate check` automatically after every code change. The agent reads the applicable ADRs, writes compliant code, and validates -- no manual check commands needed. [Sign up for beta access](https://plugins.archgate.dev).

---

## Guides: CI Integration

Source: https://cli.archgate.dev/guides/ci-integration/

Archgate checks fit into any CI system that respects exit codes. Add a single step to your pipeline and violations will block merges automatically.

## GitHub Actions

The fastest way to add Archgate to GitHub Actions is with the official [`archgate/check-action`](https://github.com/archgate/check-action). It installs the CLI, runs `archgate check --ci`, and outputs violations as inline annotations on the pull request's "Files changed" tab:

```yaml
name: Archgate
on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archgate/check-action@v1
```

That's it — no Node.js setup, no install step. If any rule reports a violation with `error` severity, the job fails with exit code 1.

### Pin a version

```yaml
- uses: archgate/check-action@v1
  with:
    version: v0.15.0
```

### Setup-only action

If you need to run Archgate commands beyond `check` (e.g. `archgate adr list --json`), use [`archgate/setup-action`](https://github.com/archgate/setup-action) to install the CLI and add it to PATH, then run whatever commands you need:

```yaml
steps:
  - uses: actions/checkout@v4
  - uses: archgate/setup-action@v1
  - run: archgate check --ci
  - run: archgate adr list --json
```

### Cross-platform workflow

Both actions support Ubuntu, macOS, and Windows runners:

```yaml
jobs:
  check:
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - uses: archgate/check-action@v1
```

### Manual setup

If you prefer not to use the official actions, you can install Archgate manually:

```yaml
steps:
  - uses: actions/checkout@v4
  - run: npm install -g archgate
  - run: archgate check
```

## GitHub Actions annotations

Use `--ci` to output violations as GitHub Actions workflow annotations. These appear inline on the pull request's "Files changed" tab, pointing directly to the offending file and line.

```yaml
- run: archgate check --ci
```

The `--ci` flag produces `::error` and `::warning` annotations in the format GitHub Actions expects. Each annotation includes the ADR ID, rule ID, file path, and line number.

:::note
The `archgate/check-action` passes `--ci` automatically — you only need this flag when running `archgate check` manually.

## Machine-readable output

Use `--json` for structured output that other tools can parse:

```yaml
- run: archgate check --json > results.json
```

The JSON output includes:

```json
{
  "pass": false,
  "total": 6,
  "passed": 5,
  "failed": 1,
  "warnings": 0,
  "errors": 1,
  "infos": 0,
  "ruleErrors": 0,
  "truncated": false,
  "results": [
    {
      "adrId": "ARCH-006",
      "ruleId": "no-unapproved-deps",
      "description": "Production dependencies must be on the approved list",
      "status": "fail",
      "totalViolations": 1,
      "shownViolations": 1,
      "violations": [
        {
          "message": "Unapproved production dependency: \"chalk\"",
          "file": "package.json",
          "severity": "error"
        }
      ],
      "durationMs": 18
    }
  ],
  "durationMs": 142
}
```

## Exit codes

| Code | Meaning          | CI behavior  |
| ---- | ---------------- | ------------ |
| 0    | All checks pass  | Job succeeds |
| 1    | Violations found | Job fails    |
| 2    | Internal error   | Job fails    |

Warnings (severity `warning`) are logged but do not affect the exit code. Only `error`-severity violations cause exit code 1.

## Narrowing scope

### Check files changed in the PR

Use `--base` to compare against the PR's base branch. This gives cross-file dependency rules the full picture of what changed:

```yaml
- run: archgate check --base origin/${{ github.base_ref }}
```

Without `--base`, the base branch is auto-detected from `origin/HEAD`. The explicit form is recommended in CI for deterministic behavior.

### Check only staged files

Use `--staged` to limit checking to git-staged files. This is useful in pre-commit hooks or when you only want to validate what is about to be committed:

```yaml
- run: archgate check --staged
```

### Check a specific ADR

Use `--adr <id>` to run rules from a single ADR:

```yaml
- run: archgate check --adr ARCH-006
```

This is useful when a PR only touches files governed by one ADR and you want faster feedback.

## Adding to an existing pipeline

If you already have a CI configuration, add Archgate as a single step after your checkout:

```yaml
# Existing pipeline
steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-node@v4
    with:
      node-version: "22"
  - run: npm ci
  - run: npm test

  # Add Archgate check
  - run: npm install -g archgate
  - run: archgate check --ci
```

No additional dependencies or configuration files are needed beyond the `.archgate/` directory already in your repository.

## Caching the installation

Cache the `~/.archgate` directory to speed up repeated installs:

```yaml
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Cache Archgate
        uses: actions/cache@v4
        with:
          path: ~/.archgate
          key: archgate-${{ runner.os }}

      - run: npm install -g archgate
      - run: archgate check --ci
```

## GitLab CI

```yaml
adr-compliance:
  image: node:22
  script:
    - npm install -g archgate
    - archgate check
```

## Standalone installer (no Node.js)

If your CI environment does not have Node.js, use the standalone installer to download a pre-built binary directly from GitHub Releases:

```yaml
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsSL https://cli.archgate.dev/install-unix | sh
      - run: ~/.archgate/bin/archgate check --ci
```

This works in any environment with `curl` and `tar` — no runtime dependencies needed. You can pin a version with the `ARCHGATE_VERSION` environment variable:

```yaml
- run: curl -fsSL https://raw.githubusercontent.com/archgate/cli/main/install.sh | ARCHGATE_VERSION=v0.11.2 sh
```

## Bun-based CI

If your CI already uses Bun, install Archgate with `bun` instead of `npm`:

```yaml
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install -g archgate
      - run: archgate check --ci
```

## Other CI systems

Archgate works with any CI system that can run shell commands. The pattern is always the same:

1. Install: `npm install -g archgate`, `bun install -g archgate`, or use the [standalone installer](/getting-started/installation/#install-standalone-recommended)
2. Run: `archgate check`
3. Check the exit code (0 = pass, 1 = violations, 2 = error)

For systems that support annotations (Azure DevOps, Buildkite, etc.), use `--json` to parse the output and emit annotations in the format your CI expects.

## Pre-commit hooks

You can also run Archgate as a local pre-commit hook. Add this to `.git/hooks/pre-commit` (or use a hook manager like Husky or Lefthook):

```bash
#!/bin/sh
archgate check --staged
```

The `--staged` flag ensures only files about to be committed are checked, keeping the hook fast.

## Verbose output

Use `--verbose` to see passing rules and timing information alongside failures. This is helpful for debugging slow checks or confirming that rules are running as expected:

```yaml
- run: archgate check --verbose
```

CI catches violations at merge time. Editor plugins catch them at coding time. With the [Claude Code](/guides/claude-code-plugin/) or [Cursor](/guides/cursor-integration/) plugin, your AI agent reads ADRs before writing code and validates compliance before you even commit. [Sign up for beta access](https://plugins.archgate.dev).

---

## Guides: Claude Code Plugin

Source: https://cli.archgate.dev/guides/claude-code-plugin/

The Archgate Claude Code plugin gives AI agents working in [Claude Code](https://claude.ai/code) built-in guardrails. Instead of relying on prompt instructions that drift over time, agents read your ADRs directly via Archgate CLI commands and validate their own code against your rules.

## What the plugin provides

The plugin adds an agent and role-based skills to Claude Code. The agent orchestrates the guardrails workflow, invoking skills as needed -- read decisions before coding, validate after, and capture new patterns for the team.

### Agent

| Agent                | Purpose                                                                     |
| -------------------- | --------------------------------------------------------------------------- |
| `archgate:developer` | General development agent that reads ADRs before coding and validates after |

The `archgate:developer` agent is set as the default agent via `.claude/settings.local.json`. It orchestrates the skills below automatically as part of its workflow.

### Skills

| Skill                      | Purpose                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------- |
| `archgate:architect`       | Validates code changes against all project ADRs for structural compliance             |
| `archgate:quality-manager` | Reviews rule coverage and proposes new ADRs when patterns emerge                      |
| `archgate:adr-author`      | Creates and edits ADRs following project conventions                                  |
| `archgate:onboard`         | One-time setup: explores the codebase, interviews the developer, creates initial ADRs |

## Installation

The Claude Code plugin is currently in beta. Run `archgate login` to sign up and authenticate.

### 1. Log in with GitHub

Authenticate with your GitHub account to obtain a plugin token:

```bash
archgate login
```

This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored securely in your OS credential manager via `git credential approve`.

### 2. Initialize your project with the plugin

Run `archgate init` in your project. If you are already logged in, the plugin is installed automatically:

```bash
archgate init
```

To explicitly request plugin installation:

```bash
archgate init --install-plugin
```

This creates `.claude/settings.local.json` with the `archgate:developer` agent and skill permissions pre-configured.

If the `claude` CLI is on your PATH, the plugin is installed automatically via:

1. `claude plugin marketplace add` (registers the Archgate marketplace)
2. `claude plugin install archgate@archgate` (installs the plugin)

If the `claude` CLI is not found, the command prints the manual commands for you to run.

### Installing the plugin on an existing project

If your project is already initialized, you can install or reinstall the plugin without re-running `archgate init`:

```bash
archgate plugin install
```

To get the authenticated repository URL for manual configuration:

```bash
archgate plugin url
```

## Initial setup with onboard

After installation, run the `archgate:onboard` skill in your project once. This skill:

1. Explores your codebase structure (directories, key files, package configuration)
2. Interviews you about your team's conventions, constraints, and architectural decisions
3. Creates an initial set of ADRs based on your responses
4. Sets up the `.archgate/` directory with your first rules

The onboard skill is designed to run once per project. After onboarding, the other skills handle day-to-day development.

## How it works in practice

The plugin follows a structured workflow for every coding task:

### 1. Read applicable ADRs

When the developer gives a coding task, the agent runs `archgate review-context` to read all ADRs that apply to the files being changed. This provides a condensed briefing with the **Decision** and **Do's and Don'ts** sections from each relevant ADR.

The agent does not write code until it has read the applicable ADRs. This is enforced by the `archgate:developer` skill.

### 2. Write code following ADR constraints

The agent writes code that complies with the constraints from the ADRs. The Do's and Don'ts sections serve as concrete guardrails -- the agent references them while coding.

### 3. Validate changes

After writing code, the agent runs `archgate check` to execute automated rules against the changes. Any violations are fixed before proceeding.

### 4. Architect review

The agent invokes `archgate:architect` to validate structural ADR compliance beyond what automated rules catch. The architect skill reviews the full context of the changes against all applicable ADRs.

### 5. Capture learnings

The agent invokes `archgate:quality-manager` to review the work and identify patterns worth capturing. The quality manager may propose new ADRs or updates to existing ones when recurring conventions emerge.

## ADR-driven refusal

When the agent encounters a task that would require violating an ADR, it refuses and explains which ADR would be violated. It then suggests how to achieve the same goal while staying compliant.

For example, if a developer asks the agent to add `chalk` as a dependency in a project governed by ARCH-006 (dependency policy), the agent will:

1. Refuse, citing ARCH-006 and the approved dependency list
2. Suggest using `styleText()` from `node:util` instead
3. Offer to implement the task using the compliant alternative

This behavior is consistent regardless of how the developer phrases the request. ADRs are treated as mandatory constraints, not suggestions.

## How the plugin accesses ADRs

The plugin uses Archgate CLI commands directly to read ADRs and run compliance checks. The key commands are:

- **`archgate review-context`** -- condensed briefings of all ADRs applicable to changed files, grouped by domain
- **`archgate check --staged`** -- automated rule checking with violation reporting
- **`archgate adr show <id>`** -- full text of a specific ADR
- **`archgate adr list`** -- inventory of all ADRs in the project with metadata
- **`archgate session-context claude-code`** -- read session transcripts for context recovery

All commands run locally and read directly from your `.archgate/adrs/` directory. No data leaves your machine.

## When to use each agent or skill

| Scenario                                     | Agent or skill             |
| -------------------------------------------- | -------------------------- |
| Starting a new project with Archgate         | `archgate:onboard`         |
| Day-to-day coding tasks                      | `archgate:developer`       |
| Reviewing a PR for ADR compliance            | `archgate:architect`       |
| Noticing a recurring pattern worth codifying | `archgate:quality-manager` |
| Creating or editing an ADR                   | `archgate:adr-author`      |

The `archgate:developer` agent orchestrates the skills automatically -- it invokes `archgate:architect` and `archgate:quality-manager` as part of its workflow. Most of the time, you only need to interact with the developer agent directly.

---

## Guides: Copilot CLI Plugin

Source: https://cli.archgate.dev/guides/copilot-cli-plugin/

The Archgate Copilot CLI plugin gives AI agents working in [GitHub Copilot CLI](https://github.com/features/copilot) built-in guardrails. Agents read your ADRs before writing code, validate after, and capture new patterns for the team -- the same workflow available in the [Claude Code plugin](/guides/claude-code-plugin/).

## How it works

Copilot CLI supports plugin installation from git repositories using `copilot plugin install`. The Archgate plugin is served from a git repository at `plugins.archgate.dev/archgate.git`, which Copilot CLI recognizes natively -- the same `.claude-plugin/plugin.json` manifest format works for both Claude Code and Copilot CLI.

## Installation

The Copilot CLI plugin is currently in beta. Run `archgate login` to sign up and authenticate before following the steps below.

### 1. Log in with GitHub

Authenticate with your GitHub account to obtain a plugin token:

```bash
archgate login
```

This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored securely in your OS credential manager via `git credential approve`.

### 2. Initialize your project with the plugin

Run `archgate init` with the `--editor copilot` flag:

```bash
archgate init --editor copilot
```

If you are already logged in and the `copilot` CLI is on your PATH, the plugin is installed automatically via:

```bash
copilot plugin install https://<github-user>:<token>@plugins.archgate.dev/archgate.git
```

If the `copilot` CLI is not found, the command prints the manual command for you to run.

To explicitly request plugin installation:

```bash
archgate init --editor copilot --install-plugin
```

To install or reinstall the plugin on an already-initialized project:

```bash
archgate plugin install --editor copilot
```

### Generated files

The command creates the `.github/copilot/` directory for plugin configuration. Plugin installation is handled separately via the `copilot plugin install` command.

### Manual installation

If the `copilot` CLI is not found during `archgate init`, you can install the plugin manually:

```bash
copilot plugin install https://<github-user>:<token>@plugins.archgate.dev/archgate.git
```

You can find your authenticated URL by running `archgate plugin url copilot`.

## What the plugin provides

The plugin adds an agent and role-based skills to Copilot CLI. The agent orchestrates the guardrails workflow, invoking skills as needed.

### Agent

| Agent                | Purpose                                                                     |
| -------------------- | --------------------------------------------------------------------------- |
| `archgate:developer` | General development agent that reads ADRs before coding and validates after |

The `archgate:developer` agent is set as the default agent via the plugin settings. It orchestrates the skills below automatically as part of its workflow.

### Skills

| Skill                      | Purpose                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------- |
| `archgate:architect`       | Validates code changes against all project ADRs for structural compliance             |
| `archgate:quality-manager` | Reviews rule coverage and proposes new ADRs when patterns emerge                      |
| `archgate:adr-author`      | Creates and edits ADRs following project conventions                                  |
| `archgate:onboard`         | One-time setup: explores the codebase, interviews the developer, creates initial ADRs |

## Initial setup with onboard

After installation, run the `archgate:onboard` skill in your project once. This skill:

1. Explores your codebase structure (directories, key files, package configuration)
2. Interviews you about your team's conventions, constraints, and architectural decisions
3. Creates an initial set of ADRs based on your responses
4. Sets up the `.archgate/` directory with your first rules

The onboard skill is designed to run once per project. After onboarding, the other skills handle day-to-day development.

## How it works in practice

The plugin follows a structured workflow for every coding task:

### 1. Read applicable ADRs

When the developer gives a coding task, the agent runs `archgate review-context` to read all ADRs that apply to the files being changed. This provides a condensed briefing with the **Decision** and **Do's and Don'ts** sections from each relevant ADR.

### 2. Write code following ADR constraints

The agent writes code that complies with the constraints from the ADRs. The Do's and Don'ts sections serve as concrete guardrails.

### 3. Validate changes

After writing code, the agent runs `archgate check` to execute automated rules against the changes. Any violations are fixed before proceeding.

### 4. Architect review

The agent invokes `archgate:architect` to validate structural ADR compliance beyond what automated rules catch.

### 5. Capture learnings

The agent invokes `archgate:quality-manager` to review the work and identify patterns worth capturing as new ADRs.

## Tips

- **Run onboard once per project** to generate your initial ADRs from your actual codebase.
- **Keep ADR rule files up to date** -- the agent enforces what the rules check for.

---

## Guides: Cursor Integration

Source: https://cli.archgate.dev/guides/cursor-integration/

Archgate integrates with [Cursor](https://cursor.com) to give AI agents built-in guardrails. The agent reads your ADRs before writing code, validates after, and captures new patterns for the team -- the same workflow available in the [Claude Code plugin](/guides/claude-code-plugin/).

## Setup

Run `archgate init` with the `--editor cursor` flag to configure Cursor integration in your project:

```bash
archgate init --editor cursor
```

The Cursor plugin is currently in beta. Run `archgate login` to sign up and authenticate.

If you have logged in via `archgate login`, the init command also installs the Archgate plugin for Cursor. The plugin provides pre-built agents, skills, and hooks that give Cursor's AI agent a full guardrails workflow.

The plugin is distributed as an authenticated tarball. The CLI downloads it and extracts skills, agents, and hooks into `~/.cursor/`. No CLI detection is needed -- files are written directly to the Cursor user directory.

To explicitly install the plugin:

```bash
archgate login              # one-time setup
archgate init --editor cursor --install-plugin
```

To install or reinstall the plugin on an already-initialized project:

```bash
archgate plugin install --editor cursor
```

### Generated files

**User scope** (`~/.cursor/`):

| File                                           | Purpose                                                             |
| ---------------------------------------------- | ------------------------------------------------------------------- |
| `~/.cursor/skills/archgate-reviewer.md`        | Validates code changes against all project ADRs                     |
| `~/.cursor/skills/archgate-lessons-learned.md` | Captures learnings and proposes new ADRs when patterns emerge       |
| `~/.cursor/skills/archgate-adr-author.md`      | Creates and edits ADRs following project conventions                |
| `~/.cursor/skills/archgate-onboard.md`         | One-time setup: explores the codebase, interviews you, creates ADRs |
| `~/.cursor/skills/archgate-cli-reference.md`   | Internal reference for AI agents with the Archgate CLI guide        |
| `~/.cursor/agents/archgate-developer.md`       | Primary development agent with the full ADR guardrails workflow     |
| `~/.cursor/agents/archgate-planner.md`         | Planning agent for scoping and breaking down work                   |

**Project scope**:

| File                 | Purpose                                                               |
| -------------------- | --------------------------------------------------------------------- |
| `.cursor/hooks.json` | `afterFileEdit` hook that runs `archgate check` after every file edit |

The `.cursor/hooks.json` file is the only file written to your project tree. It ensures `archgate check` runs automatically after every file edit, catching ADR violations in real time.

## What the plugin provides

The plugin adds agents and skills to Cursor, installed at the user scope so they are available across all your projects.

### Agents

| Name                 | Purpose                                                                     |
| -------------------- | --------------------------------------------------------------------------- |
| `archgate-developer` | General development agent that reads ADRs before coding and validates after |
| `archgate-planner`   | Planning agent for scoping work and breaking tasks into ADR-compliant steps |

Users invoke agents explicitly via `/archgate-developer` or `/archgate-planner` in the Cursor chat.

### Skills

| Name                       | Purpose                                                                       |
| -------------------------- | ----------------------------------------------------------------------------- |
| `archgate-reviewer`        | Validates code changes against all project ADRs for structural compliance     |
| `archgate-lessons-learned` | Reviews rule coverage and proposes new ADRs when patterns emerge              |
| `archgate-adr-author`      | Creates and edits ADRs following project conventions                          |
| `archgate-onboard`         | One-time setup: explores the codebase, interviews you, creates initial ADRs   |
| `archgate-cli-reference`   | Internal reference for AI agents with the complete Archgate CLI command guide |

These are the same roles available in the Claude Code plugin (`archgate:reviewer`, `archgate:lessons-learned`, etc.), adapted for Cursor's skill and agent system.

### Hooks

| Hook            | Trigger         | Action                                                     |
| --------------- | --------------- | ---------------------------------------------------------- |
| `afterFileEdit` | Every file edit | Runs `archgate check` to catch ADR violations in real time |

The hook is defined in `.cursor/hooks.json` at the project level, so it works both locally and in cloud agent environments.

## Initial setup with onboard

After installing the plugin, invoke `/archgate-developer` and ask it to run the onboard skill in your project. This skill:

1. Explores your codebase structure (directories, key files, package configuration)
2. Interviews you about your team's conventions, constraints, and architectural decisions
3. Creates an initial set of ADRs based on your responses
4. Sets up the `.archgate/` directory with your first rules

The onboard skill is designed to run once per project. After onboarding, the other skills handle day-to-day development.

## How it works in practice

Invoke `/archgate-developer` in Cursor's chat when starting a coding task. The agent follows a structured workflow for every change:

1. **Read applicable ADRs** -- The agent runs `archgate review-context` to see which ADRs apply to the files being changed. It does not write code until it has read the applicable ADRs.

2. **Write code following ADR constraints** -- The agent implements changes following the Do's and Don'ts from the applicable ADRs.

3. **Run compliance checks** -- The agent runs `archgate check` to execute automated rules. The `afterFileEdit` hook also catches violations in real time. Any violations are fixed before proceeding.

4. **Review changes** -- The agent invokes the `archgate-reviewer` skill to validate structural ADR compliance beyond what automated rules catch.

5. **Capture learnings** -- The agent invokes the `archgate-lessons-learned` skill to review the work and identify patterns worth capturing as new ADRs or updates to existing ones.

## ADR-driven refusal

When the agent encounters a task that would require violating an ADR, it refuses and explains which ADR would be violated. It then suggests how to achieve the same goal while staying compliant.

For example, if a developer asks the agent to add `chalk` as a dependency in a project governed by a dependency policy ADR, the agent will:

1. Refuse, citing the ADR and the approved dependency list
2. Suggest using the approved alternative instead
3. Offer to implement the task using the compliant approach

This behavior is consistent regardless of how the developer phrases the request. ADRs are treated as mandatory constraints, not suggestions.

## When to use each agent or skill

| Scenario                                     | Agent / Skill                                  |
| -------------------------------------------- | ---------------------------------------------- |
| Starting a new project with Archgate         | `/archgate-developer` (then ask it to onboard) |
| Day-to-day coding tasks                      | `/archgate-developer`                          |
| Planning and scoping work                    | `/archgate-planner`                            |
| Reviewing a change for ADR compliance        | `archgate-reviewer`                            |
| Noticing a recurring pattern worth codifying | `archgate-lessons-learned`                     |
| Creating or editing an ADR                   | `archgate-adr-author`                          |

The `archgate-developer` agent orchestrates the skills automatically -- it invokes `archgate-reviewer` and `archgate-lessons-learned` as part of its workflow. Most of the time, you only need to invoke `/archgate-developer` and let it run.

## Cloud agent support

Cursor supports cloud agents that run on remote VMs. These environments do not have access to `~/.cursor/`, so user-scoped skills and agents are not available. However, the `.cursor/hooks.json` file is part of your project tree and works in cloud VMs. This means `archgate check` still runs automatically after every file edit, even in cloud agent sessions.

For full governance in cloud environments, ensure `archgate` is available on the VM's PATH (e.g., via the install script in your project's setup).

## Session transcript access

The `archgate session-context cursor` command reads Cursor agent session transcripts from disk. This allows skills to access the history of the current conversation, which is useful for recovering context that may have been compacted or truncated.

The command accepts two optional flags:

- `--max-entries <n>` -- Maximum number of entries to return (default: 200, most recent entries).
- `--session-id <uuid>` -- A specific session UUID to read. If omitted, the most recent session is used.

## Tips for effective usage

- **Invoke `/archgate-developer` for coding tasks.** It orchestrates the full read-validate-capture workflow automatically.
- **Run onboard once per project.** It sets up your initial ADRs based on your actual codebase and conventions.
- **Use `archgate-reviewer` for reviews.** It validates structural compliance beyond what automated rules catch.
- **Use `archgate-lessons-learned` after resolving tricky issues.** It captures learnings so the same mistakes are not repeated.
- **Commit the `.cursor/` directory.** The `hooks.json` file ensures every team member gets `archgate check` on file edits when they clone the repository.
- **Keep ADR rules files up to date.** The agent enforces what the rules check for -- if a rule is missing, the violation will not be caught.
- **Re-run `archgate plugin install --editor cursor` to upgrade.** The service returns the latest plugin bundle on every authenticated download.

---

## Guides: Importing ADRs

Source: https://cli.archgate.dev/guides/importing-adrs/

## What are ADR packs?

An **ADR pack** is a curated collection of Architecture Decision Records bundled together under a shared theme. Each pack includes:

- An `archgate-pack.yaml` manifest with metadata (name, version, maintainers, tags)
- One or more ADR markdown files in an `adrs/` directory
- Optional companion `.rules.ts` files that enforce each decision automatically

Packs let you bootstrap a project with proven architectural conventions instead of writing everything from scratch.

## Importing from the registry

The [Archgate awesome-adrs registry](https://github.com/archgate/awesome-adrs) hosts community-maintained packs. Import one with:

```bash
archgate adr import packs/typescript-strict
```

This clones the registry, copies the ADRs into your `.archgate/adrs/` directory, and remaps IDs to fit your project's numbering scheme.

### Pinning a version

Append `@<ref>` to lock to a specific git tag or branch:

```bash
archgate adr import packs/typescript-strict@0.3.0
```

## Cherry-picking individual ADRs

You don't have to import an entire pack. Point to a specific ADR file within a pack:

```bash
archgate adr import packs/security/adrs/SEC-001-no-secrets-in-code
```

Only that single ADR (and its companion rules file, if present) will be imported.

## Importing from third-party repos

Any GitHub repository with ADR files works as a source. Use the three-segment `org/repo/path` syntax:

```bash
archgate adr import acme/company-adrs/packs/api-standards
```

This clones `https://github.com/acme/company-adrs.git` and imports from the specified subpath.

## Importing from any git URL

For non-GitHub repositories or when you need full control, pass a complete URL:

```bash
archgate adr import https://github.com/org/repo/tree/main/packs/my-pack
```

The CLI parses the GitHub `/tree/<ref>/<path>` format automatically. For other hosts, you can pass any git-cloneable URL:

```bash
archgate adr import https://gitlab.com/team/repo.git
```

## Preview with `--dry-run`

See what would be imported without writing anything:

```bash
archgate adr import packs/typescript-strict --dry-run
```

Output shows the original IDs, remapped IDs, and titles in a table.

## Listing imported ADRs with `--list`

Check what has been imported previously:

```bash
archgate adr import --list
```

This reads `.archgate/imports.json` and displays each source, version, and the ADR IDs it produced.

## How ID remapping works

When you import ADRs, the original IDs are **remapped** to match your project's domain prefixes. Each ADR's `domain` field determines which prefix it gets — for example, an ADR with `domain: frontend` becomes `FE-XXX`, while one with `domain: backend` becomes `BE-XXX`. Each domain has its own counter, so importing a pack with mixed domains produces correctly prefixed IDs without collisions.

For example, importing a pack with three frontend ADRs and two backend ADRs into a project that already has `FE-001` and `BE-001` produces:

- `FE-002`, `FE-003`, `FE-004` (frontend)
- `BE-002`, `BE-003` (backend)

The remapping ensures:

1. No ID collisions with existing ADRs
2. Each domain maintains its own numbering sequence
3. Imported rules files work immediately without manual edits

## The imports.json manifest

Every import is recorded in `.archgate/imports.json`:

```json
{
  "imports": [
    {
      "source": "packs/typescript-strict",
      "version": "0.3.0",
      "importedAt": "2026-05-10T14:32:00.000Z",
      "adrIds": ["ARCH-006", "ARCH-007", "ARCH-008"]
    }
  ]
}
```

This manifest lets you track provenance — where each imported ADR came from and when. Commit it to version control alongside your ADRs.

## Command options reference

| Option      | Description                           |
| ----------- | ------------------------------------- |
| `--yes`     | Skip the confirmation prompt          |
| `--json`    | Output results as JSON                |
| `--dry-run` | Preview changes without writing files |
| `--list`    | List previously imported ADRs         |

---

## Guides: opencode Integration

Source: https://cli.archgate.dev/guides/opencode-integration/

Archgate integrates with [opencode](https://opencode.ai) to give AI agents built-in guardrails. The agent reads your ADRs before writing code, validates after, and captures new patterns for the team -- the same workflow available in the [Claude Code plugin](/guides/claude-code-plugin/).

## Setup

Run `archgate init` with the `--editor opencode` flag to configure opencode integration in your project:

```bash
archgate init --editor opencode
```

The opencode agent bundle is currently in beta. Run `archgate login` to sign up and authenticate.

Unlike the Claude Code or Cursor integrations, the opencode agents are **not written to your project tree**. They are installed at the user scope instead — so they live on your machine, not in your repository, and are available across every project you open with opencode.

opencode uses the XDG Base Directory convention on every platform (via the `xdg-basedir` package), so the install location resolves to `$XDG_CONFIG_HOME/opencode/agents/` when that variable is set, and falls back to `$HOME/.config/opencode/agents/` otherwise. That means Windows installs land under `C:\Users\<username>\.config\opencode\agents\`, not under `%APPDATA%`:

| Platform      | Install location                               |
| ------------- | ---------------------------------------------- |
| Linux / macOS | `~/.config/opencode/agents/`                   |
| Windows       | `C:\Users\<username>\.config\opencode\agents\` |

### Authenticated install

The install step only runs when the `opencode` CLI is on your PATH. Archgate needs to confirm opencode is present before writing files into its user-scope config directory — otherwise the agents would sit in a location nothing reads. Install opencode from [opencode.ai](https://opencode.ai/docs/) first, then re-run `archgate init --editor opencode` or `archgate plugin install --editor opencode`.

If you have logged in via `archgate login` **and** `opencode` is on your PATH, the init command downloads and installs the Archgate agent bundle for opencode. The bundle provides a pre-built primary agent and four subagents that give opencode's AI a full guardrails workflow.

To explicitly install the agents:

```bash
archgate login                                  # one-time setup
archgate init --editor opencode --install-plugin
```

To install or reinstall on an already-initialized project:

```bash
archgate plugin install --editor opencode
```

The install step downloads an authenticated tarball from the Archgate plugins service and extracts the five `archgate-*.md` agent files into the opencode user-scope directory.

### Generated files (user scope)

| File                                            | Purpose                                                                  |
| ----------------------------------------------- | ------------------------------------------------------------------------ |
| `<opencode-agents>/archgate-developer.md`       | Primary agent (selectable with Tab) that runs the full ADR workflow      |
| `<opencode-agents>/archgate-architect.md`       | Subagent that validates code changes against all project ADRs            |
| `<opencode-agents>/archgate-quality-manager.md` | Subagent that captures learnings and proposes new ADRs                   |
| `<opencode-agents>/archgate-adr-author.md`      | Subagent that creates and edits ADRs following project conventions       |
| `<opencode-agents>/archgate-cli-reference.md`   | Internal reference subagent with the Archgate CLI command guide (hidden) |

`.archgate/adrs/` and `.archgate/lint/` are still created in your project as usual — only the opencode-specific agent files live outside the project tree.

## What the bundle provides

The `archgate-` prefix avoids collision with any user-authored opencode agents in the same directory. Subagents are invoked via opencode's `@-mention` syntax.

### Primary agent

| Name                 | Purpose                                                                     |
| -------------------- | --------------------------------------------------------------------------- |
| `archgate-developer` | General development agent that reads ADRs before coding and validates after |

The `archgate-developer` agent orchestrates the subagents below automatically as part of its workflow.

### Subagents

| Name                       | Purpose                                                                       |
| -------------------------- | ----------------------------------------------------------------------------- |
| `archgate-architect`       | Validates code changes against all project ADRs for structural compliance     |
| `archgate-quality-manager` | Reviews rule coverage and proposes new ADRs when patterns emerge              |
| `archgate-adr-author`      | Creates and edits ADRs following project conventions                          |
| `archgate-cli-reference`   | Internal reference for AI agents with the complete Archgate CLI command guide |

These are the same roles available in the Claude Code plugin, adapted for opencode's native primary/subagent model.

## How it works in practice

Select `archgate-developer` as your primary agent (use the Tab key in opencode) when starting a coding task. The agent follows a structured workflow for every change:

1. **Read applicable ADRs** -- The agent runs `archgate review-context` to see which ADRs apply to the files being changed. It does not write code until it has read the applicable ADRs.

2. **Write code following ADR constraints** -- The agent implements changes following the Do's and Don'ts from the applicable ADRs.

3. **Run compliance checks** -- The agent runs `archgate check` to execute automated rules. Any violations are fixed before proceeding.

4. **Architect review** -- The agent mentions `@archgate-architect` to validate structural ADR compliance beyond what automated rules catch.

5. **Capture learnings** -- The agent mentions `@archgate-quality-manager` to review the work and identify patterns worth capturing as new ADRs or updates to existing ones.

## ADR-driven refusal

When `archgate-developer` encounters a task that would require violating an ADR, it refuses and explains which ADR would be violated. It then suggests how to achieve the same goal while staying compliant.

For example, if a developer asks the agent to add `chalk` as a dependency in a project governed by a dependency policy ADR, the agent will:

1. Refuse, citing the ADR and the approved dependency list
2. Suggest using the approved alternative instead
3. Offer to implement the task using the compliant approach

This behavior is consistent regardless of how the developer phrases the request. ADRs are treated as mandatory constraints, not suggestions.

## When to use each agent or subagent

| Scenario                                     | Agent / Subagent               |
| -------------------------------------------- | ------------------------------ |
| Day-to-day coding tasks                      | `archgate-developer` (primary) |
| Reviewing a change for ADR compliance        | `@archgate-architect`          |
| Noticing a recurring pattern worth codifying | `@archgate-quality-manager`    |
| Creating or editing an ADR                   | `@archgate-adr-author`         |

The `archgate-developer` agent orchestrates the subagents automatically -- it mentions `@archgate-architect` and `@archgate-quality-manager` as part of its workflow. Most of the time, you only need to select `archgate-developer` and let it run.

## User-scope vs project-scope

The opencode bundle lives in your user-scope opencode directory rather than in `.opencode/` inside your project. Consequences:

- **One install per machine.** `archgate plugin install --editor opencode` installs the bundle globally. Every project you open with opencode sees the same `archgate-*` agents.
- **Your repo stays clean.** No `.opencode/` folder is ever created by `archgate init`. Team members who want the agents run their own `archgate plugin install --editor opencode`.
- **Upgrades are global.** Re-running `archgate plugin install --editor opencode` overwrites the existing files with the latest bundle.

## Tips for effective usage

- **Select `archgate-developer` at the start of coding sessions.** It orchestrates the full read-validate-capture workflow automatically.
- **Use `@archgate-architect` for reviews.** It validates structural compliance beyond what automated rules catch.
- **Use `@archgate-quality-manager` after resolving tricky issues.** It captures learnings so the same mistakes are not repeated.
- **Keep ADR rules files up to date.** The agent enforces what the rules check for -- if a rule is missing, the violation will not be caught.
- **Re-run `archgate plugin install --editor opencode` to upgrade.** The service returns the latest agent bundle on every authenticated download.

---

## Guides: Pre-commit Hooks

Source: https://cli.archgate.dev/guides/pre-commit-hooks/

## Overview

The `archgate check --staged` command checks only git-staged files against your ADR rules. Because it skips unstaged and untracked files, it runs fast enough to use as a pre-commit hook without slowing down your workflow.

When a check fails, the commit is blocked. Violations are printed to stderr with file paths and line numbers so you can locate and fix them immediately.

## Lefthook

[Lefthook](https://github.com/evilmartians/lefthook) is a fast, cross-platform git hooks manager. Add the following to your `lefthook.yml`:

```yaml
# lefthook.yml
pre-commit:
  commands:
    adr-check:
      run: archgate check --staged
```

Install the hook with:

```bash
lefthook install
```

## Husky

[Husky](https://typicode.github.io/husky/) is a popular git hooks tool for Node.js projects. Add the check to your pre-commit hook:

```bash
# .husky/pre-commit
archgate check --staged
```

Make sure the hook file is executable:

```bash
chmod +x .husky/pre-commit
```

## What happens when checks fail

When `archgate check --staged` finds violations, it exits with code 1. This blocks the commit. The output includes:

- The ADR ID and rule name that was violated
- The file path where the violation was found
- The line number (when available)
- A description of what the rule expects

Fix the violations, re-stage the files with `git add`, and commit again.

## Performance

The `--staged` flag restricts checks to only the files in the git staging area. This means:

- A project with hundreds of source files but only three staged files will only check those three files.
- Rules that do not match any staged files are skipped entirely.
- Typical pre-commit checks complete in under a second.

Without `--staged`, `archgate check` scans all files matched by each ADR's `files` glob pattern, which is useful for CI but slower for interactive use.

## Useful flags

| Flag         | Purpose                                                                                                                    |
| ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `--staged`   | Only check git-staged files (required for pre-commit)                                                                      |
| `--verbose`  | Show passing rules and timing information -- helpful when debugging why a check is slow or which rules are being evaluated |
| `--json`     | Output results as JSON -- useful for piping to other tools or custom reporting scripts                                     |
| `--adr <id>` | Only check rules from a specific ADR -- useful for isolating a single rule during debugging                                |
| `--ci`       | Output GitHub Actions annotations -- use this in CI workflows instead of pre-commit hooks                                  |

## Combining with other hooks

Pre-commit hooks can run multiple commands. For example, with Lefthook:

```yaml
# lefthook.yml
pre-commit:
  commands:
    lint:
      run: npm run lint
    typecheck:
      run: npm run typecheck
    adr-check:
      run: archgate check --staged
```

Each command runs independently. If any command exits with a non-zero code, the commit is blocked.

---

## Guides: Security

Source: https://cli.archgate.dev/guides/security/

Archgate executes TypeScript rules from `.rules.ts` files in your repository. This page explains the trust model, what rules can and cannot do, and how to run checks safely.

## Trust model

**`.rules.ts` files are executable code.** When you run `archgate check`, the CLI dynamically imports every `.rules.ts` companion file and runs its `check` functions. This is equivalent to running `bun .archgate/adrs/*.rules.ts` -- the code has the same capabilities as any other script on your machine.

This means:

- Only run `archgate check` on repositories you trust.
- Review `.rules.ts` files with the same scrutiny as any other source code in the project.
- In open-source projects, treat `.rules.ts` changes in pull requests as security-sensitive.

### What rules can access

Rules receive a `RuleContext` object with sandboxed file operations. All `RuleContext` methods (`readFile`, `readJSON`, `grep`, `grepFiles`, `glob`) are restricted to the project root directory -- path traversal via `../`, absolute paths, and symbolic links are blocked and throw an error.

In addition to the runtime sandbox, Archgate runs a **static analysis security scanner** on every `.rules.ts` file before executing it. The scanner parses the rule's AST and blocks files that contain dangerous patterns:

| Pattern                                                            | Blocked |
| ------------------------------------------------------------------ | ------- |
| Imports of `node:fs`, `child_process`, `net`, `http`, `vm`, etc.   | Yes     |
| `Bun.spawn()`, `Bun.write()`, `Bun.file()`, `Bun.$`                | Yes     |
| `fetch()`                                                          | Yes     |
| `eval()`, `new Function()`                                         | Yes     |
| Computed property access (`Bun[variable]`, `globalThis[variable]`) | Yes     |
| Dynamic `import()` with non-literal argument                       | Yes     |
| Assignment to `globalThis` or `process.env`                        | Yes     |

If any banned pattern is found, the rule file is **not imported or executed** and `archgate check` exits with an error.

**Safe modules that are allowed:** `node:path`, `node:url`, `node:util`, `node:crypto` -- these are utility modules with no filesystem, network, or process I/O capabilities.

The scanner raises the bar from "trivial to exploit" to "requires deliberate obfuscation that looks suspicious in code review." Well-behaved rules only use the `RuleContext` methods (`ctx.readFile`, `ctx.grep`, `ctx.glob`, etc.) and `ctx.report` for output.

### What rules cannot do

- **Write files** -- the `RuleContext` API is read-only. Rules report violations but cannot modify the codebase.
- **Escape the 30-second timeout** -- each rule is killed after 30 seconds of wall-clock time.
- **Affect other rules** -- rules from different ADRs run in parallel but share no mutable state through the context API.
- **Use dangerous APIs** -- the security scanner blocks imports of system modules (`fs`, `child_process`, `net`, etc.), Bun APIs (`Bun.spawn`, `Bun.file`), network access (`fetch`), and code generation (`eval`, `new Function`). Rule files that contain these patterns are rejected before execution.

## CI/CD best practices

Running `archgate check` in CI is safe when you control the repository content. Extra care is needed for pull requests from external contributors.

### Trusted branches

For pushes to `main` or other protected branches, `archgate check` runs code that has already been reviewed and merged. This is safe:

```yaml
on:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archgate/check-action@v1
```

### Pull requests from forks

When a pull request comes from a fork, the `.rules.ts` files in the PR may contain arbitrary code. This is the same risk as running any untrusted CI script.

**Option 1: Require approval before running.** Use GitHub's environment protection rules or `pull_request_target` with manual approval to gate CI on review:

```yaml
on:
  pull_request_target:

jobs:
  check:
    runs-on: ubuntu-latest
    environment: pr-check # Requires manual approval
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha }}
      - uses: archgate/check-action@v1
```

**Option 2: Only run checks on trusted files.** Use a separate workflow that checks out the base branch's `.rules.ts` files and runs them against the PR's source files. This ensures only reviewed rules execute.

**Option 3: Skip checks on fork PRs.** If your rules are primarily for internal governance, skip automated checks on fork PRs and run them manually after review:

```yaml
on:
  pull_request:

jobs:
  check:
    if: github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archgate/check-action@v1
```

### Least-privilege runners

Run `archgate check` on runners with minimal permissions. The job only needs read access to the repository -- no secrets, deployment keys, or write permissions are required:

```yaml
jobs:
  check:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: archgate/check-action@v1
```

## Local development

### Reviewing rules in new repositories

When cloning or forking a repository that uses Archgate, the security scanner automatically blocks dangerous patterns in `.rules.ts` files. However, you should still review rule files before running `archgate check` for the first time:

- The scanner catches explicit use of banned APIs, but sophisticated obfuscation (e.g., `Reflect.get(Bun, "spawn")`) may bypass it
- Top-level code that runs on import (before the `check` function is called) is still executed if it passes the scanner
- Well-behaved rules only use the `RuleContext` methods (`ctx.readFile`, `ctx.grep`, `ctx.glob`, etc.) and `ctx.report` for output

### Credentials

The `archgate login` command stores your authentication token in the operating system's credential manager (macOS Keychain, Windows Credential Manager, or Linux libsecret) via `git credential approve`. No credentials are written to disk as plain-text files. The token is used for plugin installation and is never sent to third parties beyond the Archgate plugins service.

- Do not share the token in CI logs. Plugin installation commands pass credentials via authenticated URLs to git, which may appear in process listings. Avoid running `archgate plugin install` with verbose logging in shared CI environments.
- To revoke access, run `archgate login logout`.

### Self-update integrity

When you run `archgate upgrade`, the CLI downloads the release binary from GitHub Releases and verifies its SHA256 checksum before extraction. If the checksum does not match, the upgrade is aborted. This protects against tampered downloads due to network interception or compromised mirrors.

## Reporting vulnerabilities

If you discover a security issue in Archgate, please report it responsibly by opening a [GitHub issue](https://github.com/archgate/cli/issues) or contacting the maintainers directly. Do not include exploit code in public issues.

---

## Guides: VS Code Plugin

Source: https://cli.archgate.dev/guides/vscode-plugin/

The Archgate VS Code plugin gives AI agents working in [VS Code](https://code.visualstudio.com/) built-in guardrails. Agents read your ADRs before writing code, validate after, and capture new patterns for the team -- the same workflow available in the [Claude Code plugin](/guides/claude-code-plugin/).

## How it works

VS Code supports **agent plugins** installed from git-based marketplaces. The Archgate plugin is served from a git repository at `plugins.archgate.dev/archgate/vscode.git`. When you add this marketplace to your VS Code user settings, VS Code discovers and installs the plugin automatically.

The plugin is served in VS Code Copilot's native `.github/plugin/` manifest format, separate from the Claude Code `.claude-plugin/` format.

## Installation

Agent plugins require **VS Code 1.110 (February 2026 release) or later**. Earlier versions do not support git-based agent plugin marketplaces. Check your version with `code --version`.

The VS Code plugin is currently in beta. Run `archgate login` to sign up and authenticate before following the steps below.

### 1. Log in with GitHub

Authenticate with your GitHub account to obtain a plugin token:

```bash
archgate login
```

This starts a GitHub Device Flow. The CLI displays a one-time code and URL -- open the URL in your browser, enter the code, and authorize. Once complete, credentials are stored securely in your OS credential manager via `git credential approve`.

### 2. Initialize your project with the plugin

Run `archgate init` with the `--editor vscode` flag:

```bash
archgate init --editor vscode
```

If you are already logged in, this command:

1. Creates the `.archgate/` directory with ADRs and lint rules
2. Adds the authenticated marketplace URL to your VS Code **user settings**
3. Downloads and installs the Archgate VS Code extension (`.vsix`) if the `code` CLI is available

The `chat.plugins.marketplaces` setting is application-scoped in VS Code, so it cannot be set per-workspace. The CLI automatically writes it to your user-level `settings.json`:

| Platform | User settings path                                      |
| -------- | ------------------------------------------------------- |
| Windows  | `%APPDATA%\Code\User\settings.json`                     |
| macOS    | `~/Library/Application Support/Code/User/settings.json` |
| Linux    | `~/.config/Code/User/settings.json`                     |

To explicitly request plugin installation:

```bash
archgate init --editor vscode --install-plugin
```

To install or reinstall the plugin on an already-initialized project:

```bash
archgate plugin install --editor vscode
```

### Generated files

The command creates or updates the following:

| File                 | Scope       | Purpose                                                |
| -------------------- | ----------- | ------------------------------------------------------ |
| User `settings.json` | User        | `chat.plugins.marketplaces` with the authenticated URL |
| Archgate extension   | Application | VS Code extension installed via `.vsix`                |

The user settings file is merged additively -- existing settings are never overwritten. VS Code's built-in default marketplaces (`github/copilot-plugins`, `github/awesome-copilot`) are preserved when the key is set for the first time.

The VS Code extension is downloaded from the Archgate plugins service and installed via `code --install-extension`. If the `code` CLI is not available, manual installation instructions are printed.

The user-level marketplace setting (added to your `settings.json`):

```json
{
  "chat.plugins.marketplaces": [
    "https://<github-user>:<token>@plugins.archgate.dev/archgate/vscode.git"
  ]
}
```

### Manual setup

If you prefer not to let the CLI modify your user settings, you can set things up manually:

**Marketplace URL:** Open VS Code's user settings JSON (`Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)") and add the `chat.plugins.marketplaces` entry shown above. You can find your authenticated URL by running `archgate plugin url vscode`.

**Extension:** Download and install the `.vsix` file directly:

```bash
curl -H "Authorization: Bearer <token>" https://plugins.archgate.dev/api/vscode -o archgate.vsix
code --install-extension archgate.vsix
rm archgate.vsix
```

Replace `<token>` with your archgate token (retrieve it via `archgate plugin url vscode`).

## What the plugin provides

The plugin adds an agent and role-based skills to VS Code's AI. The agent orchestrates the guardrails workflow, invoking skills as needed.

### Agent

| Agent                | Purpose                                                                     |
| -------------------- | --------------------------------------------------------------------------- |
| `archgate:developer` | General development agent that reads ADRs before coding and validates after |

The `archgate:developer` agent is set as the default agent via the plugin settings. It orchestrates the skills below automatically as part of its workflow.

### Skills

| Skill                      | Purpose                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------- |
| `archgate:architect`       | Validates code changes against all project ADRs for structural compliance             |
| `archgate:quality-manager` | Reviews rule coverage and proposes new ADRs when patterns emerge                      |
| `archgate:adr-author`      | Creates and edits ADRs following project conventions                                  |
| `archgate:onboard`         | One-time setup: explores the codebase, interviews the developer, creates initial ADRs |

## Initial setup with onboard

After installation, run the `archgate:onboard` skill in your project once. This skill:

1. Explores your codebase structure (directories, key files, package configuration)
2. Interviews you about your team's conventions, constraints, and architectural decisions
3. Creates an initial set of ADRs based on your responses
4. Sets up the `.archgate/` directory with your first rules

The onboard skill is designed to run once per project. After onboarding, the other skills handle day-to-day development.

## How it works in practice

The plugin follows a structured workflow for every coding task:

### 1. Read applicable ADRs

When the developer gives a coding task, the agent runs `archgate review-context` to read all ADRs that apply to the files being changed. This provides a condensed briefing with the **Decision** and **Do's and Don'ts** sections from each relevant ADR.

### 2. Write code following ADR constraints

The agent writes code that complies with the constraints from the ADRs. The Do's and Don'ts sections serve as concrete guardrails.

### 3. Validate changes

After writing code, the agent runs `archgate check` to execute automated rules against the changes. Any violations are fixed before proceeding.

### 4. Architect review

The agent invokes `archgate:architect` to validate structural ADR compliance beyond what automated rules catch.

### 5. Capture learnings

The agent invokes `archgate:quality-manager` to review the work and identify patterns worth capturing as new ADRs.

## Tips

- **Each developer runs `archgate init --editor vscode`** after `archgate login` to configure their user-level marketplace URL.
- **Run onboard once per project** to generate your initial ADRs from your actual codebase.
- **Keep ADR rule files up to date** -- the agent enforces what the rules check for.

---

## Guides: Writing ADRs

Source: https://cli.archgate.dev/guides/writing-adrs/

## Creating an ADR

Use `archgate adr create` to generate a new ADR with the standard template. The command supports both interactive and non-interactive modes.

### Interactive mode

Run the command with no arguments to get guided prompts:

```bash
archgate adr create
```

You will be prompted for:

1. **Domain** -- one of the built-in `backend`, `frontend`, `data`, `architecture`, or `general`, plus any [custom domains](/concepts/domains/#custom-domains) the project has registered via `archgate adr domain add`
2. **Title** -- a short, descriptive name for the decision
3. **File patterns** -- optional comma-separated globs that scope rule checking (e.g., `src/commands/**/*.ts`)

The CLI assigns a sequential ID based on the domain prefix (`ARCH-001`, `FE-002`, `BE-003`, etc.) and writes the file to `.archgate/adrs/`.

### Non-interactive mode

Pass `--title` and `--domain` to skip prompts:

```bash
archgate adr create --title "API Response Format" --domain backend --files "src/api/**/*.ts"
```

Available flags:

| Flag              | Description                                                           |
| ----------------- | --------------------------------------------------------------------- |
| `--title <title>` | ADR title (required for non-interactive mode)                         |
| `--domain <name>` | Domain name (built-in or [custom](/concepts/domains/#custom-domains)) |
| `--files <globs>` | Comma-separated file patterns for rule scoping                        |
| `--rules`         | Set `rules: true` in frontmatter                                      |
| `--body <md>`     | Full ADR body markdown (skip template)                                |
| `--json`          | Output the result as JSON                                             |

## The generated template

When you create an ADR without `--body`, the CLI generates a template with all standard sections:

```markdown
---
id: BE-001
title: API Response Format
domain: backend
rules: false
files: ["src/api/**/*.ts"]
---

# API Response Format

## Context

Describe the context and problem statement.

## Decision

Describe the decision that was made.

## Do's and Don'ts

### Do

-

### Don't

-

## Consequences

### Positive

-

### Negative

-

### Risks

-

## Compliance and Enforcement

Describe how this decision will be enforced.

## References

-
```

## Section-by-section writing guidance

### Context

Explain why this decision was needed. What problem prompted it? What alternatives were considered and why were they rejected?

Good context sections include:

- The problem or pain point that triggered the decision
- Alternatives that were evaluated, with brief trade-off analysis
- Any constraints that narrowed the options (team size, runtime, compatibility)

```markdown
## Context

The CLI needs a consistent pattern for defining and registering commands. As the
command surface grows (init, check, adr, login, upgrade, clean), the registration
mechanism must scale without introducing hidden coupling or making the dependency
graph opaque.

**Alternatives considered:**

- **Auto-discovery via `executableDir()`** -- Commander.js supports automatic
  command discovery by scanning a directory. This hides the dependency graph and
  makes dead command detection impossible.
- **Single-file command map** -- Simple but creates a monolithic file that grows
  with every command.
```

### Decision

State what was decided. Be specific and concrete -- this section should leave no ambiguity about what developers must do.

Include numbered constraints when the decision has multiple facets:

```markdown
## Decision

Commands live in src/commands/ and export a register\*Command(program) function.
The main entry point (src/cli.ts) explicitly imports and calls each register
function.

**Key constraints:**

1. **One command per file** -- Each .ts file defines exactly one command
2. **Explicit registration** -- Every command must be manually imported in src/cli.ts
3. **Thin commands** -- Command files handle I/O only; no business logic
```

### Do's and Don'ts

This is the section developers and AI agents reference most frequently. Write concrete examples of correct and incorrect patterns. Use real code when possible.

```markdown
## Do's and Don'ts

### Do

- Export a register\*Command function from each command module
- Keep commands thin: parse args, call helpers/engine, format output
- Use src/commands/<name>.ts for top-level commands

### Don't

- Don't put business logic in command files -- move it to src/engine/ or src/helpers/
- Don't use executableDir() for command discovery
- Don't call .parse() in command files -- the entry point handles parsing
```

### Consequences

Break consequences into three categories:

- **Positive** -- benefits the team gains from this decision
- **Negative** -- trade-offs the team accepts (every decision has them)
- **Risks** -- what could go wrong, and how you plan to mitigate it

```markdown
## Consequences

### Positive

- In-process execution enables testing without spawning subprocesses
- Explicit imports make all commands visible at a glance in src/cli.ts

### Negative

- Manual import bookkeeping -- each new command requires adding an import

### Risks

- Stale imports when commands are removed. Mitigation: TypeScript catches
  missing modules at compile time.
```

### Compliance and Enforcement

Describe how this decision is enforced. There are two enforcement mechanisms:

1. **Automated rules** -- companion `.rules.ts` files that run during `archgate check`
2. **Manual enforcement** -- what code reviewers should verify

```markdown
## Compliance and Enforcement

### Automated Enforcement

- **Archgate rule** ARCH-001/register-function-export: Scans all command files
  and verifies each exports a register\*Command function. Severity: error.

### Manual Enforcement

Code reviewers MUST verify:

1. New commands are imported and registered in src/cli.ts
2. Command files delegate to engine/helpers for business logic
```

### References

Link to related ADRs, external documentation, or relevant discussions:

```markdown
## References

- [Commander.js documentation](https://github.com/tj/commander.js)
- [ARCH-004 -- No Barrel Files](./ARCH-004-no-barrel-files.md)
- [ARCH-002 -- Error Handling](./ARCH-002-error-handling.md)
```

## Scoping rules with `files`

The `files` field in the frontmatter is an array of glob patterns. When set, `archgate check` only passes matching files to the rule's `ctx.scopedFiles`. This keeps rules focused on the code they govern.

```yaml
---
id: ARCH-001
title: Command Structure
domain: architecture
rules: true
files: ["src/commands/**/*.ts"]
---
```

If `files` is omitted, `ctx.scopedFiles` includes all project files. This is appropriate for project-wide rules like dependency policies.

By default, files listed in `.gitignore` (e.g., `node_modules/`, `dist/`) are automatically excluded from `ctx.scopedFiles`, `ctx.glob()`, and `ctx.grepFiles()`. To include gitignored files, set `respectGitignore: false`:

```yaml
---
id: BUILD-001
title: Build Output Structure
domain: architecture
rules: true
respectGitignore: false
files: ["dist/**/*.js"]
---
```

The CLI warns when an ADR's `files` patterns resolve to more than 1,000 files or the glob scan takes over 2 seconds. Broad patterns like `**/*.ts` may cause slow checks in large projects. Prefer targeting specific directories (e.g., `src/commands/**/*.ts`) over project-wide globs.

Common patterns:

| Pattern                | Matches                          |
| ---------------------- | -------------------------------- |
| `src/commands/**/*.ts` | All TypeScript files in commands |
| `src/**/*.ts`          | All TypeScript source files      |
| `package.json`         | Only the root package.json       |
| `src/api/**/*.ts`      | API layer files                  |
| `tests/**/*.test.ts`   | Test files                       |

## When to set `rules: true` vs `rules: false`

Set `rules: true` when you have a companion `.rules.ts` file with automated checks. The file must be named identically to the ADR markdown file but with a `.rules.ts` extension:

```
.archgate/adrs/
  ARCH-001-command-structure.md          # rules: true
  ARCH-001-command-structure.rules.ts    # companion rules file
  ARCH-002-error-handling.md             # rules: true
  ARCH-002-error-handling.rules.ts       # companion rules file
  GEN-001-code-review-process.md         # rules: false (no automated checks)
```

Set `rules: false` for decisions that are enforced through code review alone -- process decisions, team agreements, or guidelines that are difficult to check programmatically.

## Updating ADRs

Use `archgate adr update` to modify an existing ADR:

```bash
archgate adr update --id ARCH-001 --body "## Context\n\nUpdated context..." --title "New Title"
```

The `--id` and `--body` flags are required. All other frontmatter fields (`--title`, `--domain`, `--files`, `--rules`) are optional and preserve their existing values when omitted.

| Flag              | Description                                       |
| ----------------- | ------------------------------------------------- |
| `--id <id>`       | ADR ID to update (required)                       |
| `--body <md>`     | Full replacement body markdown (required)         |
| `--title <title>` | New title (preserves existing if omitted)         |
| `--domain <name>` | New domain (preserves existing if omitted)        |
| `--files <globs>` | New file patterns (preserves existing if omitted) |
| `--rules`         | Set `rules: true`                                 |
| `--json`          | Output the result as JSON                         |

## Tips for effective ADRs

1. **Keep each ADR focused on a single decision.** If you find yourself writing about two unrelated topics, split them into separate ADRs.

2. **Be specific in Do's and Don'ts.** Vague guidelines like "write clean code" are not actionable. Show concrete code patterns.

3. **Include real code examples.** The Do's and Don'ts section is where developers and AI agents look first. Annotated code examples make the decision unambiguous.

4. **Document alternatives you rejected.** Future contributors will ask "why didn't we use X?" The Context section should answer that question.

5. **State trade-offs honestly.** Every decision has negative consequences. Documenting them builds trust and helps the team understand what was traded away.

6. **Write rules for decisions that can be checked automatically.** If a rule can catch a violation before code review, set `rules: true` and write a companion `.rules.ts` file. See the [Writing Rules](/guides/writing-rules/) guide.

7. **Use domain prefixes to organize.** The domain field determines the ID prefix and helps filter ADRs by area. Prefer the five built-ins (`backend`, `frontend`, `data`, `architecture`, `general`); register a [custom domain](/concepts/domains/#custom-domains) only when none of them is a genuine fit.

The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) include an ADR Author skill that creates and updates ADRs following your project's conventions. The Quality Manager skill also proposes new ADRs when it detects recurring patterns. [Sign up for beta access](https://plugins.archgate.dev).

---

## Guides: Writing Rules

Source: https://cli.archgate.dev/guides/writing-rules/

Rules are TypeScript functions that check your codebase for ADR compliance. They live in companion `.rules.ts` files next to ADR markdown files and run when you execute `archgate check`.

```
.archgate/adrs/
  ARCH-001-command-structure.md          # The decision
  ARCH-001-command-structure.rules.ts    # The automated checks
```

## Basic setup

Every rules file exports a default plain object typed with `satisfies RuleSet`. Each key in the `rules` object becomes a rule ID, and each rule has a `description` and an async `check` function that receives a context object.

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "my-rule-id": {
      description: "What this rule checks",
      async check(ctx) {
        // Your check logic here
      },
    },
  },
} satisfies RuleSet;
```

:::note
The `/// <reference path>` directive may conflict with the `@typescript-eslint/triple-slash-reference` rule in ESLint or oxlint. If your project uses this rule, disable it for `.archgate/adrs/` files.

For **ESLint** (flat config):

```js
{
  files: [".archgate/adrs/*.rules.ts"],
  rules: { "@typescript-eslint/triple-slash-reference": "off" },
}
```

For **oxlint** (`.oxlintrc.json`):

```json
{
  "overrides": [
    {
      "files": [".archgate/adrs/*.rules.ts"],
      "rules": { "typescript/triple-slash-reference": "off" }
    }
  ]
}
```

A single rules file can define multiple rules:

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "first-rule": {
      description: "Checks one thing",
      async check(ctx) {
        // ...
      },
    },
    "second-rule": {
      description: "Checks another thing",
      async check(ctx) {
        // ...
      },
    },
  },
} satisfies RuleSet;
```

## The Context API

The `ctx` object passed to every `check` function provides file reading, searching, and reporting capabilities. Here is a detailed reference with examples.

### ctx.scopedFiles

An array of file paths matching the ADR's `files` glob from its frontmatter. If the ADR has no `files` field, this includes all project files.

```typescript
for (const file of ctx.scopedFiles) {
  const content = await ctx.readFile(file);
  // Check content...
}
```

Use `ctx.scopedFiles` when your rule should only apply to files the ADR governs. For example, a command structure rule scoped to `src/commands/**/*.ts` will only receive command files.

### ctx.changedFiles

An array of file paths that differ from the base branch, including uncommitted working-tree changes (staged, unstaged, and untracked non-ignored files). Auto-detected by default, or populated from `--staged` / `--base <ref>`. Useful for incremental checking and cross-file dependency rules.

```typescript
// Incremental checking -- only validate changed files
const filesToCheck = ctx.scopedFiles.filter((f) =>
  ctx.changedFiles.includes(f)
);

// Cross-file dependency -- if file A changed, file B must also change
if (ctx.changedFiles.includes("config/database.yml")) {
  if (!ctx.changedFiles.includes("deploy/manifest.yml")) {
    ctx.report.violation({
      message: "config changed but manifest was not bumped",
      file: "config/database.yml",
    });
  }
}
```

### ctx.readFile(path)

Read a file's content as a string. The path is relative to the project root.

```typescript
const content = await ctx.readFile("src/cli.ts");
```

### ctx.readJSON(path)

Read and parse a JSON file. Returns `unknown` -- cast it to the expected shape.

```typescript
const pkg = (await ctx.readJSON("package.json")) as {
  dependencies?: Record<string, string>;
};
```

### ctx.grep(file, pattern)

Search a single file with a regular expression. Returns an array of `GrepMatch` objects, each with `file`, `line`, `column`, and `content` properties.

```typescript
const matches = await ctx.grep(file, /console\.error\(/);
for (const match of matches) {
  ctx.report.violation({
    message: "Use logError() instead of console.error()",
    file: match.file,
    line: match.line,
  });
}
```

### ctx.grepFiles(pattern, fileGlob)

Search across multiple files matching a glob pattern. Returns a flat array of `GrepMatch` objects from all matching files. Files ignored by `.gitignore` are excluded by default. Set `respectGitignore: false` in the ADR frontmatter to include them.

```typescript
const matches = await ctx.grepFiles(/TODO:/, "src/**/*.ts");
for (const match of matches) {
  ctx.report.warning({
    message: "TODO comment found",
    file: match.file,
    line: match.line,
  });
}
```

### ctx.glob(pattern)

Find files by glob pattern. Returns an array of file paths relative to the project root. Files ignored by `.gitignore` are excluded by default. Set `respectGitignore: false` in the ADR frontmatter to include them.

```typescript
const testFiles = await ctx.glob("tests/**/*.test.ts");
```

### ctx.report

The reporting interface with three severity methods:

- `ctx.report.violation(detail)` -- error severity (exit code 1, blocks CI)
- `ctx.report.warning(detail)` -- warning severity (logged but does not block)
- `ctx.report.info(detail)` -- informational (logged for visibility)

Each method accepts an object with:

| Field     | Type     | Required | Description                            |
| --------- | -------- | -------- | -------------------------------------- |
| `message` | `string` | Yes      | What the violation is                  |
| `file`    | `string` | No       | Path to the offending file             |
| `line`    | `number` | No       | Line number of the violation           |
| `fix`     | `string` | No       | Suggested fix (shown to the developer) |

```typescript
ctx.report.violation({
  message: "Command file must export a register*Command function",
  file: "src/commands/check.ts",
  line: 5,
  fix: "Add: export function registerCheckCommand(program: Command) { ... }",
});
```

### ctx.projectRoot

The absolute path to the project root directory. Useful when you need to construct absolute paths.

## Severity levels

Each rule can set a default severity in its configuration. The severity determines how violations are treated:

| Severity  | Exit code | Behavior                             |
| --------- | --------- | ------------------------------------ |
| `error`   | 1         | Blocks CI, must be fixed             |
| `warning` | 0         | Logged but does not block            |
| `info`    | 0         | Informational, logged for visibility |

Set the severity in the rule definition:

```typescript
export default {
  rules: {
    "my-rule": {
      description: "...",
      severity: "warning",
      async check(ctx) {
        // Violations from this rule are warnings, not errors
        ctx.report.violation({ message: "..." });
      },
    },
  },
} satisfies RuleSet;
```

If `severity` is omitted, it defaults to `error`.

You can also report at different severities within the same rule using `ctx.report.violation()`, `ctx.report.warning()`, and `ctx.report.info()` directly.

## Rule timeout

Each rule has a 30-second execution timeout. If a rule exceeds this limit, it is treated as an error. This prevents runaway checks from blocking the pipeline.

Keep rules fast by:

- Using `ctx.grepFiles()` instead of reading every file manually
- Using `Promise.all()` to check files in parallel
- Scoping rules with the `files` frontmatter field to limit the number of files processed

## The `fix` field

The `fix` field is an optional string shown to the developer alongside the violation message. It describes what action to take to resolve the issue. Fixes are not auto-applied -- they are guidance.

```typescript
ctx.report.violation({
  message: `Unapproved dependency: "chalk"`,
  file: "package.json",
  fix: "Use styleText() from node:util instead of chalk",
});
```

When displayed, the fix appears below the violation message:

```
ARCH-006/no-unapproved-deps
  package.json
    Unapproved dependency: "chalk"
    Fix: Use styleText() from node:util instead of chalk
```

## Tips for writing rules

1. **Use `Promise.all()` for parallel file checks.** When checking multiple files independently, process them in parallel instead of sequentially.

   ```typescript
   // Good: parallel
   const checks = files.map(async (file) => {
     const content = await ctx.readFile(file);
     // ...
   });
   await Promise.all(checks);

   // Avoid: sequential
   for (const file of files) {
     const content = await ctx.readFile(file);
     // ...
   }
   ```

2. **Use `ctx.changedFiles` for incremental checking.** `ctx.changedFiles` is auto-populated with the branch diff plus uncommitted working-tree changes (or staged files with `--staged`). Filter `ctx.scopedFiles` against it to check only what changed, or use it directly for cross-file dependency rules.

3. **Keep rules focused on one concern.** A rule that checks both naming conventions and import patterns should be split into two rules with separate IDs.

4. **Use `ctx.grepFiles()` over manual iteration.** When searching for a pattern across many files, `ctx.grepFiles()` is more efficient than reading each file and running a regex.

5. **Provide actionable `fix` messages.** A fix like "Don't do this" is not helpful. Tell the developer exactly what to do instead.

6. **Filter out non-applicable files early.** If your rule only applies to certain files within the scope, filter `ctx.scopedFiles` before processing:

   ```typescript
   const commandFiles = ctx.scopedFiles.filter((f) => !f.endsWith("index.ts"));
   ```

7. **Handle missing files gracefully.** If your rule reads a specific file like `package.json`, wrap the read in a try/catch and return early if the file does not exist.

## Opt-out directives

There are two ways to handle exceptions in Archgate: **engine-level suppression** (works with any rule automatically) and **custom rule-level directives** (implemented by the rule author for domain-specific opt-outs).

### Engine-level suppression

Archgate supports inline `archgate-ignore` comments that suppress violations without modifying the rule itself. The engine parses these comments and filters matching violations before reporting.

**Next-line suppression** — suppresses the violation on the immediately following line:

```typescript
// archgate-ignore ARCH-006/no-unapproved-deps legacy dep, migration planned for Q3

```

**File-level suppression** — suppresses all matching violations anywhere in the file:

```typescript
// archgate-ignore-file ARCH-005/test-mirrors-src generated file, no manual test
```

**Multiple rules** — stack comments to suppress more than one rule on the same line:

```typescript
// archgate-ignore ARCH-006/no-unapproved-deps legacy dep
// archgate-ignore ARCH-003/use-style-text third-party lib handles colors

```

Consecutive suppression comments all target the first non-suppression line that follows.

The format is `ADR-ID/rule-id` followed by a reason. The reason is **required** — a suppression without a reason is ignored and produces a warning:

```
[suppression] Suppression for ARCH-006/no-unapproved-deps is missing a reason src/foo.ts:1
```

Both `//` and `#` comment styles are supported, so suppressions work in TypeScript, JavaScript, YAML, Python, shell scripts, and other file types your rules may scan.

:::tip
Unused suppression comments (comments that don't match any violation) also produce warnings, helping you clean up stale exceptions as code evolves.

### Custom rule-level directives

For domain-specific opt-outs, rule authors can implement their own comment-based directives inside the `check` function. This pattern gives the rule full control over the directive syntax, placement, and validation.

```typescript
// In your .rules.ts file:
async check(ctx) {
  const files = await ctx.glob("src/components/**/*Connected.tsx");

  for (const file of files) {
    const content = await ctx.readFile(file);

    // Support opt-out directive at the top of the file
    if (/^\/\/\s*@no-presentational:/u.test(content.trimStart())) continue;

    // ... rule logic that may report a violation ...
    ctx.report.violation({
      message: "Missing presentational component",
      file,
      fix: 'Add "// @no-presentational: <reason>" at the top of the file to opt out',
    });
  }
}
```

The developer opts out by adding the directive to their file:

```typescript
// @no-presentational: this component only redirects, no UI to render

```

### When to use which

| Approach          | Best for                                         | Who controls it          |
| ----------------- | ------------------------------------------------ | ------------------------ |
| `archgate-ignore` | Ad-hoc exceptions for any rule                   | Developer using the rule |
| Custom directive  | Domain-specific opt-outs with structured reasons | Rule author              |

Use `archgate-ignore` when a developer needs to suppress a one-off violation. Use custom directives when the opt-out is a first-class concept in your rule's domain — for example, marking a component as intentionally unpaired, or a file as auto-generated.

## Next steps

- [Common Rule Patterns](/examples/common-rule-patterns/) — Copy-pasteable patterns organized by category: dependency management, import restrictions, file structure, code quality, database schema, and architecture boundaries.
- [Rule API Reference](/reference/rule-api/) — Full reference for all rule API types and functions.
- [CI Integration](/guides/ci-integration/) — Wire `archgate check` into your pipeline to enforce rules on every PR.

---

## Reference: ADR Schema

Source: https://cli.archgate.dev/reference/adr-schema/

Every Archgate ADR is a Markdown file stored in `.archgate/adrs/` with YAML frontmatter that defines the decision's identity and scope. This page documents the frontmatter schema, markdown section structure, and validation behavior.

## Frontmatter Schema

The YAML frontmatter block sits between `---` delimiters at the top of the file.

```yaml
---
id: ARCH-001
title: Command Structure
domain: architecture
rules: true
files: ["src/commands/**/*.ts"]
---
```

### Fields

| Field              | Type       | Required | Description                                                                                                                                                                                                                          |
| ------------------ | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`               | `string`   | Yes      | Unique identifier. Must be non-empty. Convention: `PREFIX-NNN` (e.g., `ARCH-001`).                                                                                                                                                   |
| `title`            | `string`   | Yes      | Human-readable title of the decision. Must be non-empty.                                                                                                                                                                             |
| `domain`           | `string`   | Yes      | A registered domain name in lowercase kebab-case. Built-ins: `backend`, `frontend`, `data`, `architecture`, `general`. Custom domains are those registered via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). |
| `rules`            | `boolean`  | Yes      | Whether this ADR has a companion `.rules.ts` file with automated checks.                                                                                                                                                             |
| `files`            | `string[]` | No       | Glob patterns that scope which files the rules apply to.                                                                                                                                                                             |
| `respectGitignore` | `boolean`  | No       | Whether to filter out `.gitignore`d files. Defaults to `true`.                                                                                                                                                                       |

### id

The ADR identifier. By convention, it uses the domain prefix followed by a zero-padded sequence number (e.g., `ARCH-001`, `BE-003`). The `archgate adr create` command generates IDs automatically.

Any non-empty string is valid, but following the prefix convention keeps ADRs organized and sortable.

### title

A short, descriptive name for the architectural decision. Displayed in `archgate adr list` output and used as the heading when AI agents reference the ADR.

### domain

Groups related ADRs together. The domain also determines the ID prefix used by `archgate adr create`.

Projects can extend the built-in set with custom domains via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). Custom domain → prefix mappings live in `.archgate/config.json` and are merged with the built-ins at read time.

### rules

Set to `true` when this ADR has a companion `.rules.ts` file. When `archgate check` runs, it skips ADRs where `rules` is `false`.

### files

An optional array of glob patterns that scope the rule's file coverage. When present, `ctx.scopedFiles` in the rules file only contains files matching these patterns. When absent, all project files are in scope.

```yaml
files: ["src/commands/**/*.ts"]
```

Multiple patterns can be specified:

```yaml
files: ["src/api/**/*.ts", "src/middleware/**/*.ts"]
```

### respectGitignore

Controls whether `.gitignore`d files are excluded from `ctx.scopedFiles`, `ctx.glob()`, and `ctx.grepFiles()`. Defaults to `true` when omitted -- gitignored files (e.g., `node_modules/`, `dist/`) are automatically filtered out.

Set to `false` when a rule intentionally needs to inspect ignored files, such as checking build output structure:

```yaml
respectGitignore: false
files: ["dist/**/*.js"]
```

When `respectGitignore` is `false`, all files matched by the `files` globs are included regardless of `.gitignore` rules. When not inside a git repository, this field has no effect -- all matched files are included.

---

## Domain Prefixes

Each domain maps to a prefix used in the ADR ID convention.

### Built-in domains

| Domain         | Prefix | Example ID |
| -------------- | ------ | ---------- |
| `backend`      | `BE`   | `BE-001`   |
| `frontend`     | `FE`   | `FE-001`   |
| `data`         | `DATA` | `DATA-001` |
| `architecture` | `ARCH` | `ARCH-001` |
| `general`      | `GEN`  | `GEN-001`  |

The `archgate adr create` command uses this mapping to auto-generate IDs.

### Custom domains

Projects can register additional domain → prefix mappings via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). Once registered, custom domains behave like built-ins: `archgate adr create --domain <name>` auto-generates IDs using the associated prefix, and ADRs with custom domains parse cleanly.

See the [Domains concept page](/concepts/domains/) for guidance on when to introduce a custom domain.

---

## File Naming Convention

ADR files follow a naming convention that encodes the ID and a human-readable slug:

```
{ID}-{slug}.md              # The document
{ID}-{slug}.rules.ts        # The companion rules file (optional)
```

For example:

```
ARCH-001-command-structure.md
ARCH-001-command-structure.rules.ts
```

The slug is a kebab-case version of the title, auto-generated by `archgate adr create`.

---

## Markdown Sections

After the frontmatter, the ADR body follows a standard section structure. While Archgate does not enforce specific sections, the following structure is recommended for consistency.

### Context

Describes the problem or situation that prompted the decision. Include alternatives that were considered and why they were rejected.

```markdown
## Context

The CLI returns errors in inconsistent formats. Some commands print raw
stack traces, others print nothing, and a few use `console.error()` with
custom formatting.

**Alternatives considered:**

- **No standard** -- Let each command handle errors its own way. Simple
  but leads to an inconsistent user experience.
- **Try/catch wrapper** -- A global try/catch at the CLI entry point.
  Loses context about which command failed.
```

### Decision

States the decision itself and its key constraints. This is the primary section AI agents read before writing code.

```markdown
## Decision

All commands MUST use `logError()` from `src/helpers/log.ts` for error
output. Commands MUST NOT call `console.error()` directly.
```

### Do's and Don'ts

Concrete, actionable guidance split into two sub-sections. These act as a quick-reference checklist for developers and AI agents.

```markdown
## Do's and Don'ts

### Do

- Use `logError(message, detail?)` for all error output
- Include a suggested fix in the detail parameter when possible
- Exit with code 1 for user errors, code 2 for internal errors

### Don't

- Don't call `console.error()` directly in command files
- Don't print stack traces to users
- Don't exit without printing an error message first
```

### Consequences

Split into three sub-sections that document trade-offs.

```markdown
## Consequences

### Positive

- Consistent error formatting across all commands
- Machine-parseable error output when combined with `--json`

### Negative

- Requires importing `logError` in every command file
- Cannot use built-in error formatting from libraries

### Risks

- New contributors may use `console.error()` by habit. Mitigated by the
  automated rule that scans for direct `console.error()` calls.
```

### Compliance and Enforcement

Describes how the decision is enforced through automated rules and manual review.

```markdown
## Compliance and Enforcement

### Automated Enforcement

- **Archgate rule** ARCH-002/no-console-error: Scans command files for
  `console.error()` calls. Severity: error.

### Manual Enforcement

Code reviewers MUST verify:

1. Error messages are actionable and include context
2. Exit codes match the error type (1 for user, 2 for internal)
```

### References

Links to related ADRs, external documentation, or design documents.

```markdown
## References

- [ARCH-001 -- Command Structure](./ARCH-001-command-structure.md)
- [Node.js process.exit documentation](https://nodejs.org/api/process.html#processexitcode)
```

---

## Companion Rules File

When `rules: true`, Archgate looks for a companion file with the same name but `.rules.ts` extension.

```
ARCH-002-error-handling.md          # rules: true in frontmatter
ARCH-002-error-handling.rules.ts    # companion rules file
```

The rules file must export a default `RuleSet` using a plain object with `satisfies RuleSet`:

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "no-console-error": {
      description: "Use logError() instead of console.error()",
      async check(ctx) {
        for (const file of ctx.scopedFiles) {
          const matches = await ctx.grep(file, /console\.error\(/);
          for (const match of matches) {
            ctx.report.violation({
              message: "Use logError() instead of console.error()",
              file: match.file,
              line: match.line,
              fix: "Import logError from src/helpers/log and use it instead",
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

See the [Rule API](/reference/rule-api/) for the complete TypeScript API reference.

---

## Validation

The YAML frontmatter is validated at parse time using a Zod schema. Invalid frontmatter causes a parse error with a descriptive message.

### Required fields

If a required field is missing, the ADR fails to parse:

```
Invalid ADR frontmatter in ARCH-001-example.md:
  - domain: Required
```

### Invalid domain format

If `domain` is not a valid kebab-case identifier (e.g., has uppercase letters or spaces):

```
Invalid ADR frontmatter in ARCH-001-example.md:
  - domain: domain must be lowercase kebab-case (e.g. 'backend', 'ml-ops')
```

Note: the parser accepts any name that matches the kebab-case pattern. Whether a specific name is "known" to the project — and therefore has a prefix that `archgate adr create` can use — depends on the built-in set plus any custom domains registered via [`archgate adr domain add`](/reference/cli/adr/#archgate-adr-domain). Creating an ADR with an unregistered domain name fails with a "Unknown ADR domain" error that suggests running `archgate adr domain add`.

### Type mismatches

If `rules` is a string instead of a boolean:

```
Invalid ADR frontmatter in ARCH-001-example.md:
  - rules: Expected boolean, received string
```

ADRs that fail validation are skipped by `archgate check` and reported as errors.

---

## Reference: archgate adr

Source: https://cli.archgate.dev/reference/cli/adr/

## archgate adr create

Create a new ADR interactively or via flags.

```bash
archgate adr create [options]
```

When run without `--title` and `--domain`, the command prompts interactively for the domain, title, and optional file patterns. When both `--title` and `--domain` are provided, it runs non-interactively.

The ADR ID is auto-generated with the domain prefix and the next available sequence number (e.g., `ARCH-002`, `BE-001`).

### Options

| Option               | Description                                                                                                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--title <title>`    | ADR title (skip interactive prompt)                                                                                                                                             |
| `--domain <domain>`  | ADR domain. Built-ins: `backend`, `frontend`, `data`, `architecture`, `general`. Custom domains must first be registered via [`archgate adr domain add`](#archgate-adr-domain). |
| `--files <patterns>` | File patterns, comma-separated                                                                                                                                                  |
| `--body <markdown>`  | Full ADR body markdown (skip template)                                                                                                                                          |
| `--rules`            | Set `rules: true` in frontmatter                                                                                                                                                |
| `--json`             | Output as JSON                                                                                                                                                                  |

### Examples

Interactive mode:

```bash
archgate adr create
```

Non-interactive mode:

```bash
archgate adr create \
  --title "API Response Envelope" \
  --domain backend \
  --files "src/api/**/*.ts" \
  --rules
```

---

## archgate adr list

List all ADRs in the project.

```bash
archgate adr list [options]
```

### Options

| Option              | Description      |
| ------------------- | ---------------- |
| `--json`            | Output as JSON   |
| `--domain <domain>` | Filter by domain |

### Examples

List all ADRs in table format:

```bash
archgate adr list
```

```
ID          Domain        Rules  Title
────────────────────────────────────────────────────────
ARCH-001    architecture  true   Command Structure
ARCH-002    architecture  true   Error Handling
BE-001      backend       true   API Response Envelope
```

List ADRs as JSON:

```bash
archgate adr list --json
```

Filter by domain:

```bash
archgate adr list --domain backend
```

---

## archgate adr show

Print a specific ADR by ID.

```bash
archgate adr show <id>
```

Prints the full ADR content (frontmatter and body) to stdout.

### Arguments

| Argument | Description                         |
| -------- | ----------------------------------- |
| `<id>`   | ADR ID (e.g., `ARCH-001`, `BE-003`) |

### Example

```bash
archgate adr show ARCH-001
```

---

## archgate adr update

Update an existing ADR by ID.

```bash
archgate adr update --id <id> --body <markdown> [options]
```

Replaces the ADR body with the provided markdown. Frontmatter fields (`--title`, `--domain`, `--files`, `--rules`) are updated only when explicitly passed; otherwise the existing values are preserved.

### Options

| Option               | Required | Description                                                                                                                                                                     |
| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--id <id>`          | Yes      | ADR ID to update (e.g., `ARCH-001`)                                                                                                                                             |
| `--body <markdown>`  | Yes      | Full replacement ADR body markdown                                                                                                                                              |
| `--title <title>`    | No       | New ADR title (preserves existing if omitted)                                                                                                                                   |
| `--domain <domain>`  | No       | New domain. Built-ins: `backend`, `frontend`, `data`, `architecture`, `general`. Custom domains must first be registered via [`archgate adr domain add`](#archgate-adr-domain). |
| `--files <patterns>` | No       | New file patterns, comma-separated (preserves existing if omitted)                                                                                                              |
| `--rules`            | No       | Set `rules: true` in frontmatter                                                                                                                                                |
| `--json`             | No       | Output as JSON                                                                                                                                                                  |

### Example

```bash
archgate adr update \
  --id ARCH-001 \
  --title "Updated Command Structure" \
  --body "## Context\n\nUpdated context..."
```

---

## archgate adr domain

Manage custom ADR domains. Custom domains are name → ID-prefix mappings persisted in `.archgate/config.json` and merged with the five built-ins (`backend`, `frontend`, `data`, `architecture`, `general`) at read time.

Use this command when a decision doesn't cleanly fit any built-in domain. Before registering a new one, check whether the decision can be folded under an existing domain — built-ins are the default and a custom domain should only be introduced when no built-in is a genuine fit.

```bash
archgate adr domain <subcommand> [options]
```

### Subcommands

| Subcommand                                | Description                                                    |
| ----------------------------------------- | -------------------------------------------------------------- |
| `archgate adr domain list`                | Show all merged (built-in + custom) domains and their prefixes |
| `archgate adr domain add <name> <prefix>` | Register a custom domain                                       |
| `archgate adr domain remove <name>`       | Unregister a custom domain (built-ins cannot be removed)       |

### Naming rules

- `<name>` — lowercase kebab-case, 2–32 chars (e.g., `security`, `ml-ops`)
- `<prefix>` — uppercase letters, digits, or underscores, 2–10 chars (e.g., `SEC`, `MLOPS`)
- Custom names and prefixes cannot collide with built-ins or with any other custom entry.

### Options

| Option   | Applies to      | Description    |
| -------- | --------------- | -------------- |
| `--json` | all subcommands | Output as JSON |

### Examples

List built-in and custom domains:

```bash
archgate adr domain list
```

```
Domain          Prefix    Source
────────────────────────────────
architecture    ARCH      default
backend         BE        default
data            DATA      default
frontend        FE        default
general         GEN       default
security        SEC       custom
```

Register a custom domain:

```bash
archgate adr domain add security SEC
```

Remove a custom domain:

```bash
archgate adr domain remove security
```

---

## archgate adr import

Import ADRs from the registry or a git repository.

```bash
archgate adr import <source...> [options]
```

The command clones the source, reads ADR files, remaps IDs to fit the local project's sequence, and writes them to `.archgate/adrs/`. It tracks imports in `.archgate/imports.json` so they can later be checked for upstream updates via [`archgate adr sync`](#archgate-adr-sync).

### Arguments

| Argument      | Description                                      |
| ------------- | ------------------------------------------------ |
| `<source...>` | Registry path(s), `org/repo/path`, or git URL(s) |

### Options

| Option      | Description                     |
| ----------- | ------------------------------- |
| `--yes`     | Skip confirmation prompt        |
| `--json`    | Output as JSON                  |
| `--dry-run` | Preview changes without writing |
| `--list`    | List previously imported ADRs   |

### Examples

Import from the registry:

```bash
archgate adr import archgate/packs/typescript
```

Import from a git repository:

```bash
archgate adr import https://github.com/acme/adr-packs.git
```

Preview what would be imported without writing any files:

```bash
archgate adr import archgate/packs/typescript --dry-run
```

Import non-interactively (skip confirmation):

```bash
archgate adr import archgate/packs/typescript --yes
```

List previously imported ADRs:

```bash
archgate adr import --list
```

---

## archgate adr sync

Check for upstream updates to imported ADRs.

```bash
archgate adr sync [source...] [options]
```

The command compares local imported ADRs against their upstream source and shows which sections changed. In interactive mode, it prompts for each changed ADR with three choices: keep local, take upstream, or skip.

### Arguments

| Argument      | Description                                            |
| ------------- | ------------------------------------------------------ |
| `[source...]` | Optional source filter(s) — sync only matching imports |

### Options

| Option    | Description                              |
| --------- | ---------------------------------------- |
| `--check` | Exit 1 if upstream has updates (CI mode) |
| `--yes`   | Skip confirmation prompts                |
| `--json`  | Output as JSON                           |

### Examples

Check all imported ADRs for upstream updates:

```bash
archgate adr sync
```

Check only imports from a specific source:

```bash
archgate adr sync archgate/packs/typescript
```

CI mode — fail the build if any imported ADR is outdated:

```bash
archgate adr sync --check
```

Accept all upstream updates non-interactively:

```bash
archgate adr sync --yes
```

---

## Reference: archgate check

Source: https://cli.archgate.dev/reference/cli/check/

Run all automated ADR compliance checks against the codebase.

```bash
archgate check [options] [files...]
```

Loads every ADR with `rules: true` in its frontmatter, executes the companion `.rules.ts` file, and reports violations with file paths and line numbers. When file paths are provided as positional arguments, only ADRs whose `files` patterns match those files are executed.

## Options

| Option               | Description                                                                       |
| -------------------- | --------------------------------------------------------------------------------- |
| `--staged`           | Only check git-staged files (useful for pre-commit hooks)                         |
| `--base [ref]`       | Compare changed files against a base ref (auto-detects when omitted)              |
| `--json`             | Machine-readable JSON output                                                      |
| `--ci`               | GitHub Actions annotation format                                                  |
| `--adr <id>`         | Only check rules from a specific ADR                                              |
| `--verbose`          | Show passing rules and timing info                                                |
| `--max-warnings <n>` | Fail (exit 1) when the warning count exceeds `n`. Use `0` to fail on any warning. |

## Arguments

| Argument     | Description                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------- |
| `[files...]` | Optional file paths to scope checks to. Only ADRs whose `files` patterns match will run. Supports stdin piping. |

## Exit codes

| Code | Meaning                                                                 |
| ---- | ----------------------------------------------------------------------- |
| 0    | All rules pass. No violations found.                                    |
| 1    | One or more violations detected, or warnings exceeded `--max-warnings`. |
| 2    | Rule execution error (e.g., malformed rule, security scanner block).    |

## Examples

Check the entire project:

```bash
archgate check
```

Check only staged files before committing:

```bash
archgate check --staged
```

Check all files changed on the current branch vs `main`:

```bash
archgate check --base main
```

Check a single ADR:

```bash
archgate check --adr ARCH-001
```

Treat any warning as a failure (useful in CI):

```bash
archgate check --max-warnings 0
```

Check specific files (only matching ADRs run):

```bash
archgate check src/foo.ts src/bar.ts
```

Pipe from git (check only changed files):

```bash
git diff --name-only | archgate check --json
```

Get JSON output for CI integration:

```bash
archgate check --json
```

Get GitHub Actions annotations:

```bash
archgate check --ci
```

## Changed files detection

By default, `archgate check` auto-detects the base branch and populates `ctx.changedFiles` with the branch diff (`git diff <base>...HEAD`) plus any uncommitted working-tree changes (staged, unstaged, and untracked non-ignored files). This enables cross-file dependency rules to work locally -- not just in CI -- and ensures edits that haven't been committed yet are still checked.

The base ref is resolved in priority order:

| Priority | Source                               | `changedFiles` populated with                           |
| -------- | ------------------------------------ | ------------------------------------------------------- |
| 1        | `--staged`                           | Git staging area only                                   |
| 2        | `--base <ref>`                       | `git diff <ref>...HEAD` + working-tree changes          |
| 3        | `.archgate/config.json` `baseBranch` | `git diff <resolved-ref>...HEAD` + working-tree changes |
| 4        | Git auto-detect                      | `git diff <detected-ref>...HEAD` + working-tree changes |
| 5        | Detection fails                      | Empty (full-scan mode)                                  |

Auto-detection tries `origin/HEAD`, then `origin/main`, `origin/master`, local `main`, and local `master`. To set a project default, add `baseBranch` to `.archgate/config.json`:

```json
{ "baseBranch": "main" }
```

## Diagnostics

During execution, `archgate check` emits warnings for common misconfigurations that may cause slow or unexpected results:

| Warning                             | Condition                                                                                        | Recommendation                                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |
| **Broad file scope**                | An ADR's `files` patterns resolve to more than 1,000 files or the glob scan takes over 2 seconds | Narrow the `files` patterns in the ADR frontmatter to target only the relevant source directories |
| **Unscoped gitignore opt-out**      | `respectGitignore: false` is set without a `files` scope                                         | Add `files` patterns to avoid scanning all files including `node_modules/`, `.git/`, etc.         |
| **All files excluded by gitignore** | Explicit `files` patterns match files, but every match is excluded by `.gitignore`               | Set `respectGitignore: false` in the ADR frontmatter to include gitignored files                  |

These warnings appear in the standard output and do not affect the exit code. They also appear in JSON output when `--json` is used (as violations with `"severity": "warning"`).

By default, warnings (both diagnostics and rule-reported `"severity": "warning"` violations) never change the exit code. Pass `--max-warnings <n>` to make `archgate check` exit 1 when the total warning count exceeds `n`. `--max-warnings 0` fails on any warning. When the threshold is exceeded the JSON output's `warningsExceeded` field is `true` and `pass` is `false`.

## JSON output format

When `--json` is used, the output is a single JSON object:

```json
{
  "pass": false,
  "total": 4,
  "passed": 3,
  "failed": 1,
  "warnings": 0,
  "errors": 1,
  "infos": 0,
  "ruleErrors": 0,
  "warningsExceeded": false,
  "truncated": false,
  "results": [
    {
      "adrId": "ARCH-001",
      "ruleId": "register-function-export",
      "description": "Command file must export a register*Command function",
      "status": "fail",
      "totalViolations": 1,
      "shownViolations": 1,
      "violations": [
        {
          "message": "Command file must export a register*Command function",
          "file": "src/commands/broken.ts",
          "line": 1,
          "endLine": 1,
          "endColumn": 42,
          "severity": "error"
        }
      ],
      "durationMs": 12
    }
  ],
  "durationMs": 42
}
```

### Violation fields

| Field       | Type    | Description                                             |
| ----------- | ------- | ------------------------------------------------------- |
| `message`   | string  | What the violation is                                   |
| `file`      | string? | Relative file path                                      |
| `line`      | number? | Start line (1-based)                                    |
| `endLine`   | number? | End line (1-based) -- for precise editor highlighting   |
| `endColumn` | number? | End column (0-based) -- for precise editor highlighting |
| `fix`       | string? | Suggested fix (guidance only)                           |
| `severity`  | string  | `"error"`, `"warning"`, or `"info"`                     |

### Blocked rule files

When a rule file is blocked by the security scanner (e.g., uses `Bun.spawn()`) or a companion `.rules.ts` file is missing, the result appears in the JSON output with `status: "error"` and `ruleId: "security-scan"`. Violations include the exact file and line of the blocked code (or the `rules: true` line in the ADR for missing companions).

---

## Reference: archgate clean

Source: https://cli.archgate.dev/reference/cli/clean/

Remove the CLI cache directory.

```bash
archgate clean
```

Removes `~/.archgate/`, which stores cached data such as update check timestamps. Safe to run at any time -- the directory is recreated automatically when needed.

## Example

```bash
archgate clean
```

```
/home/user/.archgate cleaned up
```

---

## Reference: archgate doctor

Source: https://cli.archgate.dev/reference/cli/doctor/

Check the system environment, installation method, and editor integrations. Useful for diagnosing configuration issues and sharing debug context in bug reports.

```bash
archgate doctor [options]
```

## Options

| Option   | Description             |
| -------- | ----------------------- |
| `--json` | Machine-readable output |

## Output sections

- **System** -- OS, architecture, WSL detection, Bun and Node versions
- **Archgate** -- CLI version, install method (binary, proto, local, global-pm), config directory, telemetry and login status
- **Project** -- Whether an `.archgate/` project exists, ADR count, domains
- **Editor CLIs** -- Whether `claude`, `cursor`, `code` (VS Code), `copilot`, and `git` are available on PATH
- **Project Integrations** -- Whether editor-specific plugin files exist in the current project (`.claude/settings.local.json`, `.cursor/rules/archgate-governance.mdc`, `.vscode/settings.json`, `.github/copilot/instructions.md`)

## Example

```bash
archgate doctor
```

```
System
  OS:           win32/x64
  Bun:          1.3.11
  Node:         v24.3.0

Archgate
  Version:      0.25.1
  Install:      binary
  Exec path:    /home/user/.archgate/bin/archgate
  Config dir:   /home/user/.archgate OK
  Telemetry:    enabled
  Logged in:    yes

Project
  ADRs:         5 (3 with rules)
  Domains:      ARCH, GEN

Editor CLIs
  claude:       OK
  cursor:       MISSING
  code (vscode):OK
  copilot:      MISSING
  git:          OK

Project Integrations
  Claude:       OK (.claude/settings.local.json)
  Cursor:       MISSING (.cursor/rules/archgate-governance.mdc)
  VS Code:      OK (.vscode/settings.json)
  Copilot:      MISSING (.github/copilot/instructions.md)
```

---

## Reference: CLI Commands

Source: https://cli.archgate.dev/reference/cli/

## Global options

These options are available on all commands:

| Option            | Description                |
| ----------------- | -------------------------- |
| `--version`, `-V` | Print the Archgate version |
| `--help`, `-h`    | Show help for any command  |

```bash
archgate --version
archgate check --help
```

## Commands

| Command                                          | Description                                           |
| ------------------------------------------------ | ----------------------------------------------------- |
| [`archgate login`](./login/)                     | Authenticate with GitHub                              |
| [`archgate init`](./init/)                       | Set up linting and rules enforcement                  |
| [`archgate plugin`](./plugin/)                   | Manage editor plugins                                 |
| [`archgate check`](./check/)                     | Run ADR compliance checks                             |
| [`archgate adr`](./adr/)                         | Create, list, show, and update ADRs                   |
| [`archgate review-context`](./review-context/)   | Pre-compute review context for CI/editor integrations |
| [`archgate session-context`](./session-context/) | Read AI editor session transcripts                    |
| [`archgate upgrade`](./upgrade/)                 | Upgrade Archgate to the latest version                |
| [`archgate doctor`](./doctor/)                   | Check system environment and editor integrations      |
| [`archgate clean`](./clean/)                     | Remove the CLI cache directory                        |

---

## Reference: archgate init

Source: https://cli.archgate.dev/reference/cli/init/

Set up Archgate linting and rules enforcement in the current project.

```bash
archgate init [options]
```

Creates the `.archgate/` directory with an example ADR, companion rules file, and linter configuration. Optionally configures editor integration for AI agent workflows and installs the Archgate editor plugin.

## Options

| Option              | Default  | Description                                                                           |
| ------------------- | -------- | ------------------------------------------------------------------------------------- |
| `--editor <editor>` | `claude` | Editor integration to configure (`claude`, `cursor`, `vscode`, `copilot`, `opencode`) |
| `--install-plugin`  | auto     | Install the Archgate editor plugin (requires prior `archgate login`)                  |

When `--install-plugin` is passed, the CLI installs the Archgate plugin for the selected editor. If the flag is omitted, the CLI auto-detects: it installs the plugin when valid credentials exist (from a previous `archgate login`) and skips otherwise.

## Plugin installation behavior

**Claude Code:** If the `claude` CLI is on your PATH, the plugin is installed automatically via `claude plugin marketplace add` and `claude plugin install`. If the `claude` CLI is not found, the command prints the manual installation commands instead.

**Cursor:** Downloads an authenticated tarball of skills, agents, and hooks into `~/.cursor/`. Also writes `.cursor/hooks.json` to the project for cloud agent compatibility. No CLI detection needed.

**opencode:** Requires the `opencode` CLI to be on your PATH — if it's not, the install is skipped and a message prompts you to install opencode first. When present, the CLI downloads an authenticated tarball of agent files from the Archgate plugins service and extracts it into the user-scope opencode agents directory (`$XDG_CONFIG_HOME/opencode/agents/`, falling back to `$HOME/.config/opencode/agents/` on every platform including Windows — opencode uses XDG paths via `xdg-basedir` and does not read `%APPDATA%`). No files are written to the project tree. See the [opencode integration guide](/guides/opencode-integration/) for details.

## Output

```
Initialized Archgate governance in /path/to/project
  adrs/          - architecture decision records
  lint/          - linter-specific rules
  .claude/       - Claude Code settings configured

Archgate plugin installed for Claude Code.
```

When `--editor cursor` is used, the output shows `.cursor/` for project-level files and notes that user-scope components were installed to `~/.cursor/`.

## Base branch detection

When run inside a git repository, `archgate init` auto-detects the base branch and saves it to `.archgate/config.json` as the `baseBranch` field. This allows `archgate check` to skip branch detection on every run, saving 1-4 git subprocess calls.

The detection tries `origin/HEAD`, `origin/main`, `origin/master`, local `main`, and local `master` (first match wins). If none are found (e.g., not a git repo), no `baseBranch` is written.

Re-running `archgate init` does **not** overwrite a manually configured `baseBranch`. See [Configuration -- `baseBranch`](/reference/configuration/#basebranch) for details.

## Generated structure

```
.archgate/
  adrs/
    GEN-001-example.md           # Example ADR
    GEN-001-example.rules.ts     # Example rules file
  lint/
    README.md                    # Linter rules guide
```

---

## Reference: archgate login

Source: https://cli.archgate.dev/reference/cli/login/

Authenticate with GitHub to access Archgate editor plugins. If you are not registered yet, the CLI handles signup automatically -- it prompts for your email, editor preference (Claude Code, VS Code, Copilot CLI, or Cursor), and use case, then registers you before completing the login.

```bash
archgate login
```

Starts a GitHub Device Flow (OAuth). The CLI displays a one-time code and a URL. Open the URL in your browser, enter the code, and authorize the Archgate GitHub OAuth App. Once authorized, the CLI exchanges your GitHub identity for an Archgate plugin token and stores it securely in your OS credential manager (macOS Keychain, Windows Credential Manager, or Linux libsecret) via `git credential approve`. No credentials are written to disk as plain-text files.

If your GitHub account is not yet registered, the CLI prompts for your email, preferred editor, and use case, then signs you up automatically.

Credentials are required to install editor plugins via `archgate init --install-plugin`. The CLI itself (check, init, etc.) works without login.

Editor plugins are currently in beta. Run `archgate login` to sign up and authenticate.

## Subcommands

| Subcommand               | Description                               |
| ------------------------ | ----------------------------------------- |
| `archgate login`         | Authenticate (skips if already logged in) |
| `archgate login status`  | Show current authentication status        |
| `archgate login logout`  | Remove stored credentials                 |
| `archgate login refresh` | Re-authenticate and claim a new token     |

## Examples

Log in for the first time:

```bash
archgate login
```

```
Authenticating with GitHub...

Open https://github.com/login/device in your browser
and enter the code: ABCD-1234

Waiting for authorization...
GitHub user: yourname

Your GitHub account yourname is not yet registered.
Let's sign you up now.

Email: you@example.com
Editor: Claude Code
Use case: Enforcing ADRs in our monorepo

Submitting signup request...
Claiming archgate plugin token...

Authenticated as yourname. Plugin access is now available.
Run `archgate init` to set up a project with the archgate plugin.
```

If the project already has `.archgate/adrs/`, the final line reads:

```
Run `archgate check` to validate your project against its ADRs.
```

## Troubleshooting

### TLS/corporate proxy errors

If `archgate login` fails with a TLS certificate error (common behind corporate proxies), point your runtime at your organization's CA bundle using the `NODE_EXTRA_CA_CERTS` environment variable.

On macOS/Linux:

```bash
export NODE_EXTRA_CA_CERTS=/path/to/your-corporate-ca.pem
archgate login
```

On Windows (PowerShell):

```powershell
$env:NODE_EXTRA_CA_CERTS = "C:\path\to\your-corporate-ca.pem"
archgate login
```

On Windows (cmd):

```cmd
set NODE_EXTRA_CA_CERTS=C:\path\to\your-corporate-ca.pem
archgate login
```

On Windows (Git Bash):

```bash
export NODE_EXTRA_CA_CERTS=/c/path/to/your-corporate-ca.pem
archgate login
```

Ask your IT team for the correct certificate path if you are unsure.

Check login status:

```bash
archgate login status
```

```
Logged in as yourname (since 2026-02-28)
```

Log out:

```bash
archgate login logout
```

Re-authenticate:

```bash
archgate login refresh
```

---

## Reference: archgate plugin

Source: https://cli.archgate.dev/reference/cli/plugin/

Manage Archgate editor plugins independently of `archgate init`.

```bash
archgate plugin <subcommand> [options]
```

Use `archgate plugin` to install plugins or retrieve the authenticated repository URL on projects that have already been initialized.

## Subcommands

### archgate plugin url

Print the plugin repository URL for manual tool configuration.

```bash
archgate plugin url [options]
```

| Option              | Default  | Description                                                         |
| ------------------- | -------- | ------------------------------------------------------------------- |
| `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`, `opencode`) |

The URL can be used to manually configure editor tools. Credentials are provided automatically by your git credential manager (stored during `archgate login`). For example, to add the Archgate marketplace in Claude Code:

```bash
claude plugin marketplace add "$(archgate plugin url)"
claude plugin install archgate@archgate
```

For VS Code, the URL points to a separate plugin repository:

```bash
archgate plugin url --editor vscode
```

### archgate plugin install

Install the Archgate plugin for the specified editor on an already-initialized project.

```bash
archgate plugin install [options]
```

| Option              | Default  | Description                                                         |
| ------------------- | -------- | ------------------------------------------------------------------- |
| `--editor <editor>` | `claude` | Target editor (`claude`, `cursor`, `vscode`, `copilot`, `opencode`) |

Installation behavior varies by editor:

- **Claude Code:** Auto-installs via `claude` CLI if available; prints manual commands otherwise.
- **Copilot CLI:** Auto-installs via `copilot` CLI if available; prints manual commands otherwise.
- **Cursor:** Downloads an authenticated tarball and extracts skills, agents, and hooks into `~/.cursor/`. No CLI detection needed — files are written directly to the Cursor user directory.
- **VS Code:** Installs the VS Code extension (`.vsix`) via `code` CLI if available; prints manual instructions otherwise.
- **opencode:** Requires the `opencode` CLI to be on PATH — skips the install with a clear message otherwise. When present, downloads an authenticated tarball of agent files and extracts it into the user-scope opencode agents directory. `archgate plugin url --editor opencode` prints "N/A" — opencode has no marketplace URL. See the [opencode integration guide](/guides/opencode-integration/) for details.

## Examples

Get the plugin URL for manual configuration:

```bash
archgate plugin url
```

Install the plugin for Claude Code:

```bash
archgate plugin install
```

Install the plugin for Cursor:

```bash
archgate plugin install --editor cursor
```

Install the agent bundle for opencode:

```bash
archgate plugin install --editor opencode
```

---

## Reference: archgate review-context

Source: https://cli.archgate.dev/reference/cli/review-context/

Pre-compute review context with ADR briefings for changed files. Designed for CI and editor plugin integrations that need a summary of which ADRs apply to the files being changed.

```bash
archgate review-context [options]
```

## Options

| Option              | Description                                                          |
| ------------------- | -------------------------------------------------------------------- |
| `--staged`          | Only include git-staged files                                        |
| `--base [ref]`      | Compare changed files against a base ref (auto-detects when omitted) |
| `--run-checks`      | Include ADR compliance check results                                 |
| `--domain <domain>` | Filter to a single domain                                            |

## Example

```bash
archgate review-context --staged
```

---

## Reference: archgate session-context

Source: https://cli.archgate.dev/reference/cli/session-context/

Read AI editor session transcripts for the project. Useful for auditing what an AI agent did during a coding session.

```bash
archgate session-context <subcommand> [options]
```

## Subcommands

### archgate session-context claude-code

Read the Claude Code session transcript for the project.

```bash
archgate session-context claude-code [options]
```

| Option              | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| `--max-entries <n>` | Maximum entries to return (default: 200)                           |
| `--skip <n>`        | Skip the N most recent sessions (useful when running as sub-agent) |

### archgate session-context copilot

Read the Copilot CLI session transcript for the project. Sessions are matched by their workspace `cwd` field.

```bash
archgate session-context copilot [options]
```

| Option              | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| `--max-entries <n>` | Maximum entries to return (default: 200)                           |
| `--skip <n>`        | Skip the N most recent sessions (useful when running as sub-agent) |
| `--session-id <id>` | Specific session UUID to read                                      |

### archgate session-context cursor

Read the Cursor agent session transcript for the project.

```bash
archgate session-context cursor [options]
```

| Option              | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| `--max-entries <n>` | Maximum entries to return (default: 200)                           |
| `--skip <n>`        | Skip the N most recent sessions (useful when running as sub-agent) |
| `--session-id <id>` | Specific session UUID to read                                      |

### archgate session-context opencode

Read the opencode session transcript for the project. Sessions are matched by the project `path` field in session metadata.

```bash
archgate session-context opencode [options]
```

| Option              | Description                                                        |
| ------------------- | ------------------------------------------------------------------ |
| `--max-entries <n>` | Maximum entries to return (default: 200)                           |
| `--skip <n>`        | Skip the N most recent sessions (useful when running as sub-agent) |
| `--session-id <id>` | Specific session ID to read                                        |

## Examples

Read the latest Claude Code session:

```bash
archgate session-context claude-code
```

Read a specific Cursor session:

```bash
archgate session-context cursor --session-id abc123
```

Read the latest Copilot CLI session:

```bash
archgate session-context copilot
```

Read the latest opencode session:

```bash
archgate session-context opencode
```

Read the parent session (skip the sub-agent's own session):

```bash
archgate session-context claude-code --skip 1
```

---

## Reference: archgate telemetry

Source: https://cli.archgate.dev/reference/cli/telemetry/

Manage anonymous usage data collection for the Archgate CLI. Telemetry is opt-out: enabled by default, never captures personally identifiable information, and anonymizes the client IP server-side.

```bash
archgate telemetry <subcommand>
```

See [CLI telemetry](/reference/telemetry/) for the full privacy policy, the list of events emitted, and how telemetry interacts with `ARCHGATE_TELEMETRY=0` and CI environments.

## Subcommands

| Subcommand                   | Description                                         |
| ---------------------------- | --------------------------------------------------- |
| `archgate telemetry status`  | Show whether telemetry is enabled for this CLI user |
| `archgate telemetry enable`  | Enable anonymous usage data collection              |
| `archgate telemetry disable` | Disable anonymous usage data collection             |

All three subcommands read and write `~/.archgate/config.json`, which persists the opt-in state and the anonymous install ID used as the telemetry `distinct_id`.

## Examples

Check the current state:

```bash
archgate telemetry status
```

```
Telemetry is enabled.
Anonymous usage data helps improve Archgate. No personal information is collected.

To disable: `archgate telemetry disable` or set ARCHGATE_TELEMETRY=0
Learn more: https://cli.archgate.dev/reference/telemetry
```

Disable telemetry:

```bash
archgate telemetry disable
```

```
Telemetry disabled. No usage data will be collected.
```

Re-enable telemetry:

```bash
archgate telemetry enable
```

```
Telemetry enabled. Thank you for helping improve Archgate.
```

## Environment variable override

Setting `ARCHGATE_TELEMETRY=0` (or `false`, `no`, `off`, case-insensitive) disables telemetry for a single invocation regardless of the persisted state. Use this in CI or shared environments where you want opt-out without mutating the user's config:

```bash
ARCHGATE_TELEMETRY=0 archgate check
```

`archgate telemetry status` detects the override and reports:

```
Telemetry is disabled (ARCHGATE_TELEMETRY environment variable).
```

When the override is in effect, running `archgate telemetry enable` persists the opt-in but prints a note that the env var continues to disable telemetry until it is unset.

---

## Reference: archgate upgrade

Source: https://cli.archgate.dev/reference/cli/upgrade/

Upgrade Archgate to the latest version.

```bash
archgate upgrade
```

Checks GitHub Releases for the latest published version. If a newer version is available, the command auto-detects how Archgate was installed and runs the appropriate upgrade strategy. If already up-to-date, prints a message and exits.

## Options

| Option      | Description                                |
| ----------- | ------------------------------------------ |
| `--plugins` | Also update editor plugins after upgrading |

## Install method detection

The upgrade command inspects the running binary path to determine the install method, then delegates to the matching strategy:

| Install method                          | Detection                                      | Upgrade action                                                                                                                                           |
| --------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Binary install** (`~/.archgate/bin/`) | Binary lives inside `~/.archgate/bin/`         | Downloads the latest binary from GitHub Releases and replaces the existing one                                                                           |
| **Proto**                               | Binary lives inside `~/.proto/tools/archgate/` | Runs `proto install archgate latest --pin`                                                                                                               |
| **Local dev dependency**                | Binary lives inside `node_modules/`            | Detects the package manager from the nearest lockfile (bun, pnpm, yarn, or npm) and runs the appropriate add command (e.g. `bun add -d archgate@latest`) |
| **Global package manager**              | Binary lives in a global bin directory         | Detects which package manager owns the global bin directory and runs its upgrade command (e.g. `npm install -g archgate@latest`)                         |

If no specific method is detected, the command falls back to `npm install -g archgate@latest`.

## Plugin updates

After a successful upgrade, the CLI offers to update your editor plugins. In an interactive terminal, you get a confirmation prompt:

```
Archgate upgraded to 0.35.0 successfully.
? Would you like to update your editor plugins too? (Y/n)
```

The CLI auto-detects installed editors (Claude Code, Cursor, VS Code, Copilot CLI, opencode) and runs the plugin install for each selected editor. Plugin update failures are reported but do not affect the exit code -- the CLI upgrade itself is already complete.

Use `--plugins` to skip the prompt and update all detected editors automatically:

```bash
archgate upgrade --plugins
```

:::note
Plugin updates require authentication. If you are not logged in, the CLI prints a reminder to run `archgate login` first.

## Examples

Upgrade the CLI:

```bash
archgate upgrade
```

```
Checking for latest Archgate release...
Upgrading 0.34.0 -> 0.35.0...
Archgate upgraded to 0.35.0 successfully.
```

Upgrade and update all editor plugins in one step:

```bash
archgate upgrade --plugins
```

---

## Reference: Configuration

Source: https://cli.archgate.dev/reference/configuration/

The `.archgate/config.json` file stores project-level configuration that is committed to version control and shared across the team.

This file is created automatically by `archgate init` (to store the auto-detected base branch and any custom domains) or when you manually add configuration. It lives inside the `.archgate/` directory at your project root.

## Schema

```json
{
  "domains": { "security": "SEC", "compliance": "COMP" },
  "paths": { "adrs": "docs/adrs", "rules": "docs/adrs" },
  "baseBranch": "main"
}
```

### `domains`

Custom domain-to-prefix mappings. See [Custom Domains](/concepts/domains/#custom-domains) for details.

| Key    | Type     | Description                                                                                 |
| ------ | -------- | ------------------------------------------------------------------------------------------- |
| _name_ | `string` | Domain name (lowercase kebab-case, 2-32 chars) maps to an ID prefix (uppercase, 2-10 chars) |

These are merged with the built-in domains (`backend`, `frontend`, `data`, `architecture`, `general`) at read time. Custom entries cannot override built-in names or prefixes.

### `baseBranch`

Base branch for change detection in `archgate check`. When set, `archgate check` skips the auto-detection probes and uses this value directly for `ctx.changedFiles` population via `git diff <baseBranch>...HEAD`.

| Type     | Default         | Description                                             |
| -------- | --------------- | ------------------------------------------------------- |
| `string` | _(auto-detect)_ | Branch name or remote ref (e.g., `main`, `origin/main`) |

This field is **auto-populated** by `archgate init` when a git repository is detected. The auto-detection tries `origin/HEAD`, `origin/main`, `origin/master`, local `main`, and local `master` (first match wins). Re-running `archgate init` does not overwrite a manually configured value.

You can also set it manually:

```json
{ "baseBranch": "main" }
```

See [`archgate check` -- Changed files detection](/reference/cli/check/#changed-files-detection) for the full resolution priority.

### `paths`

Override default directories for ADRs and rules.

| Field   | Type     | Default          | Description                               |
| ------- | -------- | ---------------- | ----------------------------------------- |
| `adrs`  | `string` | `.archgate/adrs` | Relative path to the ADR directory        |
| `rules` | `string` | `.archgate/lint` | Relative path to the rules/lint directory |

Both fields are optional. When omitted, the default `.archgate/adrs/` and `.archgate/lint/` directories are used.

#### Path validation

- Paths **must be relative** to the project root -- absolute paths (e.g., `/docs/adrs`, `C:\docs\adrs`) are rejected.
- Paths **must not contain `..` segments** -- traversal above the project root is not allowed (e.g., `../other-repo/adrs` is rejected).
- Paths use forward slashes (`/`) as separators, matching standard glob conventions.

## Custom ADR directory

By default, ADRs live in `.archgate/adrs/`. To store them in a different directory (e.g., `docs/adrs/`), add a `paths` section to `.archgate/config.json`:

```json
{ "paths": { "adrs": "docs/adrs" } }
```

After adding the configuration:

1. Create the target directory (e.g., `mkdir -p docs/adrs`)
2. Move existing ADR files and their companion `.rules.ts` files from `.archgate/adrs/` to the new directory
3. Run `archgate check` to verify the rules still load correctly

All CLI commands (`archgate adr list`, `archgate adr create`, `archgate check`, `archgate review-context`) automatically read the configured directory.

:::caution
The `.archgate/` directory must still exist -- it is the project marker used by the CLI to locate your project root. Do not delete it after configuring custom paths.

### Example: monorepo documentation folder

A common pattern is placing ADRs alongside other documentation:

```
my-project/
  .archgate/
    config.json          # { "paths": { "adrs": "docs/adrs" } }
    lint/
    rules.d.ts
  docs/
    adrs/
      ARCH-001-api-design.md
      ARCH-001-api-design.rules.ts
      BE-001-database-access.md
      BE-001-database-access.rules.ts
    rules.d.ts           # auto-generated by archgate check
    guides/
    ...
  src/
    ...
```

## Notes

- The `paths` configuration is a **team-wide setting** -- it is committed to version control and applies to all team members. There is no user-level override for ADR paths.
- Changing the configuration requires manually editing `.archgate/config.json` after running `archgate init`.
- The `rules.d.ts` type definitions file is automatically written to both `.archgate/` and the parent of the configured ADR directory, so companion `.rules.ts` files resolve their `/// <reference path="../rules.d.ts" />` directive correctly.

---

## Reference: Privacy Policy

Source: https://cli.archgate.dev/reference/privacy-policy/

For the full Archgate Privacy Policy, please visit:

**[archgate.dev/privacy-policy](https://archgate.dev/privacy-policy)**

The sections below summarize the most relevant points for CLI users. The canonical policy on the website is the legally binding version.

**Data controller:** Dasolve AS (Org.nr 936 035 019), Lillogata 5P, 0484 Oslo, Norway. Contact: [privacy@archgate.dev](mailto:privacy@archgate.dev).

## Summary for CLI users

### What the CLI collects

Archgate collects **anonymous usage analytics** (via PostHog) and **crash reports** (via Sentry) to improve the tool. No personal information, source code, file content, or AI prompts are ever collected by the CLI itself. See the [Telemetry](/reference/telemetry/) page for a detailed breakdown of every data point.

**Legal basis:** Legitimate interest under GDPR Article 6(1)(f). See our [Legitimate Interest Assessment](https://archgate.dev/legitimate-interest-assessment).

### Data storage and retention

| Service       | Data                         | Region         | Retention                |
| ------------- | ---------------------------- | -------------- | ------------------------ |
| PostHog Cloud | Anonymous usage analytics    | EU (Frankfurt) | 1 year                   |
| Sentry Cloud  | Crash reports                | EU (Frankfurt) | 90 days                  |
| Turso         | Plugins Service account data | EU             | Until deletion requested |

Data is transmitted via reverse proxies at `n.archgate.dev` (analytics) and `s.archgate.dev` (errors) — transparent forwarders operated by Dasolve AS on Cloudflare, with no logging or storage.

### Archgate Plugins Service

When you sign up via `archgate login`, the **Plugins Service** (`plugins.archgate.dev`) collects personal information: your **email address**, **GitHub username**, **editor choice**, and a **use case description**. This data is used to provision your account and send a welcome email. Authentication tokens are stored as SHA-256 hashes on our servers; on your machine, credentials are kept in your OS credential manager (never as plain-text files).

By creating an account, you agree to the [Terms of Service](https://archgate.dev/terms-of-service). See the [full privacy policy](https://archgate.dev/privacy-policy) for complete details.

### How to opt out

```bash
# Environment variable (immediate, per-session or in shell profile)
export ARCHGATE_TELEMETRY=0

# Or persistently via the CLI
archgate telemetry disable
```

Note: telemetry opt-out disables CLI analytics and crash reporting. It does not affect the Plugins Service account data, which is required for plugin access. To delete your account data, contact [privacy@archgate.dev](mailto:privacy@archgate.dev).

### Your rights

- **Access:** Request a copy of your data — email [privacy@archgate.dev](mailto:privacy@archgate.dev) with your install ID (from `~/.archgate/config.json` or `archgate telemetry status`).
- **Erasure:** Request deletion of historical data — email with your install ID. Completed within 30 days.
- **Object:** Disable telemetry at any time via `archgate telemetry disable`.
- **Portability:** Request data export in JSON or CSV format.
- **Complaint:** Contact the Norwegian Data Protection Authority ([Datatilsynet](https://www.datatilsynet.no)).

### What the docs site collects

This documentation site (`cli.archgate.dev`) uses [Cloudflare Web Analytics](https://www.cloudflare.com/web-analytics/), a privacy-first analytics service. Cloudflare Web Analytics does not use cookies, does not track individual visitors, and does not collect personal information. It provides aggregate page-view and performance metrics only.

PostHog is also used on this site with **cookieless, memory-only tracking** (`persistence: "memory"`). No cookies are set, no localStorage is written, and no data persists between page loads.

---

## Reference: Rule API

Source: https://cli.archgate.dev/reference/rule-api/

Archgate rules are TypeScript files that export a plain object typed with `satisfies RuleSet`. Each rule receives a `RuleContext` with utilities for searching files, reading content, and reporting violations.

## RuleSet

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "my-rule-id": {
      description: "Human-readable description of what this rule checks",
      severity: "error", // optional, defaults to "error"
      async check(ctx) {
        // Rule logic here
      },
    },
  },
} satisfies RuleSet;
```

A rules file default-exports a plain object with a `rules` record keyed by rule ID. Keys become the rule IDs that appear in check output and violation reports. The `satisfies RuleSet` annotation provides type checking without wrapping in a function call.

```typescript
type RuleSet = { rules: Record<string, RuleConfig> };
```

---

## RuleConfig

Each rule in the record must conform to the `RuleConfig` interface.

```typescript
interface RuleConfig {
  description: string;
  severity?: Severity;
  check: (ctx: RuleContext) => Promise<void>;
}
```

| Field         | Type                                  | Required | Description                                            |
| ------------- | ------------------------------------- | -------- | ------------------------------------------------------ |
| `description` | `string`                              | Yes      | Human-readable description shown in check output       |
| `severity`    | `Severity`                            | No       | Default severity for violations. Defaults to `"error"` |
| `check`       | `(ctx: RuleContext) => Promise<void>` | Yes      | Async function containing the rule logic               |

---

## RuleContext

The `check` function receives a `RuleContext` object with the project state and utility methods.

```typescript
interface RuleContext {
  projectRoot: string;
  scopedFiles: string[];
  changedFiles: string[];
  glob(pattern: string): Promise<string[]>;
  grep(file: string, pattern: RegExp): Promise;
  grepFiles(pattern: RegExp, fileGlob: string): Promise;
  readFile(path: string): Promise<string>;
  readJSON(path: string): Promise<unknown>;
  report: RuleReport;
}
```

### Properties

#### projectRoot

```typescript
projectRoot: string;
```

Absolute path to the project root directory (where `.archgate/` lives).

#### scopedFiles

```typescript
scopedFiles: string[];
```

Files matching the ADR's `files` glob patterns from its frontmatter. If the ADR has no `files` field, this contains all project files. Use this as the primary file list for your rule checks.

#### changedFiles

```typescript
changedFiles: string[];
```

Files that have been modified according to git. By default, this is auto-populated with the branch diff against the detected base branch (e.g., `origin/main`) plus any uncommitted working-tree changes (staged, unstaged, and untracked non-ignored files). When `--staged` is used, this contains only staged files. When `--base <ref>` is used, this contains all files changed since that ref plus uncommitted working-tree changes. Empty when base detection fails or no changes are found. Use this to build cross-file dependency rules (e.g., "if file A changed, file B must also change").

#### report

```typescript
report: RuleReport;
```

The reporting interface for recording violations, warnings, and informational messages. See [RuleReport](#rulereport) below.

### Methods

#### glob

```typescript
glob(pattern: string): Promise<string[]>;
```

Find files matching a glob pattern relative to the project root. Returns an array of file paths. Files ignored by `.gitignore` are excluded by default. Set `respectGitignore: false` in the ADR frontmatter to include them.

```typescript
const testFiles = await ctx.glob("tests/**/*.test.ts");
```

#### grep

```typescript
grep(file: string, pattern: RegExp): Promise;
```

Search a single file for lines matching a regular expression. Returns an array of `GrepMatch` objects with file path, line number, column, and matched content.

```typescript
const matches = await ctx.grep(file, /console\.error\(/);
```

#### grepFiles

```typescript
grepFiles(pattern: RegExp, fileGlob: string): Promise;
```

Search multiple files matching a glob pattern for lines matching a regular expression. Combines `glob` and `grep` into a single call. Files ignored by `.gitignore` are excluded by default. Set `respectGitignore: false` in the ADR frontmatter to include them.

```typescript
const matches = await ctx.grepFiles(/TODO:/i, "src/**/*.ts");
```

#### readFile

```typescript
readFile(path: string): Promise<string>;
```

Read the contents of a file as a string. The path is relative to the project root.

```typescript
const content = await ctx.readFile("src/config.ts");
```

#### readJSON

```typescript
readJSON(path: string): Promise<unknown>;
```

Read and parse a JSON file. The path is relative to the project root. Returns the parsed value as `unknown` -- cast to the expected type in your rule.

```typescript
const pkg = (await ctx.readJSON("package.json")) as {
  dependencies?: Record<string, string>;
};
```

---

## RuleReport

The reporting interface for recording check results. Each method accepts a detail object describing the issue.

```typescript
interface RuleReport {
  violation(detail: ReportDetail): void;
  warning(detail: ReportDetail): void;
  info(detail: ReportDetail): void;
}
```

#### violation

```typescript
report.violation(detail: ReportDetail): void;
```

Report a rule violation. Violations cause the check to fail with exit code 1. Use for hard constraints that must not be merged.

#### warning

```typescript
report.warning(detail: ReportDetail): void;
```

Report a warning. Warnings appear in check output but do not cause the check to fail. Use for non-blocking guidance.

#### info

```typescript
report.info(detail: ReportDetail): void;
```

Report an informational message. Does not affect the check exit code. Use for suggestions or notes.

### ReportDetail

The detail object passed to `violation`, `warning`, and `info`.

```typescript
interface ReportDetail {
  message: string;
  file?: string;
  line?: number;
  endLine?: number;
  endColumn?: number;
  fix?: string;
}
```

| Field       | Type     | Required | Description                                                         |
| ----------- | -------- | -------- | ------------------------------------------------------------------- |
| `message`   | `string` | Yes      | Human-readable description of the issue                             |
| `file`      | `string` | No       | File path where the issue was found                                 |
| `line`      | `number` | No       | Start line number (1-based)                                         |
| `endLine`   | `number` | No       | End line number (1-based) — for precise editor range highlighting   |
| `endColumn` | `number` | No       | End column number (0-based) — for precise editor range highlighting |
| `fix`       | `string` | No       | Suggested fix or remediation action                                 |

When `endLine` and `endColumn` are provided, editors (VS Code, Cursor) can highlight the exact expression that violates the rule, rather than the entire line. If omitted, the full line at `line` is highlighted.

---

## GrepMatch

Returned by `ctx.grep()` and `ctx.grepFiles()`.

```typescript
interface GrepMatch {
  file: string;
  line: number;
  column: number;
  content: string;
}
```

| Field     | Type     | Description                               |
| --------- | -------- | ----------------------------------------- |
| `file`    | `string` | Project-relative path to the matched file |
| `line`    | `number` | Line number of the match (1-based)        |
| `column`  | `number` | Column number of the match (1-based)      |
| `content` | `string` | Full content of the matched line          |

---

## Severity

```typescript
type Severity = "error" | "warning" | "info";
```

| Value       | Exit code impact | Description                     |
| ----------- | ---------------- | ------------------------------- |
| `"error"`   | Causes exit 1    | Hard constraint, blocks merges  |
| `"warning"` | No impact        | Non-blocking guidance           |
| `"info"`    | No impact        | Informational, suggestions only |

---

## ViolationDetail

The internal representation of a reported issue, used in check output and JSON results.

```typescript
interface ViolationDetail {
  ruleId: string;
  adrId: string;
  message: string;
  file?: string;
  line?: number;
  endLine?: number;
  endColumn?: number;
  fix?: string;
  severity: Severity;
}
```

| Field       | Type       | Description                                            |
| ----------- | ---------- | ------------------------------------------------------ |
| `ruleId`    | `string`   | Rule ID from the `rules` object key                    |
| `adrId`     | `string`   | ADR ID from the frontmatter                            |
| `message`   | `string`   | Human-readable description                             |
| `file`      | `string?`  | File path where the issue was found                    |
| `line`      | `number?`  | Start line number (1-based)                            |
| `endLine`   | `number?`  | End line (1-based) — for precise editor highlighting   |
| `endColumn` | `number?`  | End column (0-based) — for precise editor highlighting |
| `fix`       | `string?`  | Suggested fix                                          |
| `severity`  | `Severity` | Effective severity of this violation                   |

---

## Inline suppression

Violations can be suppressed in source code using `archgate-ignore` comments. The engine handles this automatically — rules do not need any special logic.

```typescript
// archgate-ignore ARCH-006/no-unapproved-deps legacy dep, migration planned

```

A reason is required. File-level suppression uses `archgate-ignore-file`. Stack multiple comments to suppress more than one rule on the same line. See [Opt-out directives](/guides/writing-rules/#opt-out-directives) for full details and custom directive patterns.

---

## Reference: Telemetry

Source: https://cli.archgate.dev/reference/telemetry/

Archgate collects **anonymous usage data** to help us understand how the CLI is used, prioritize features, and fix crashes. This page explains exactly what is collected, what is not, and how to opt out.

## What we collect

### Usage analytics (PostHog)

When you run an Archgate command, we record:

- **Command name** and **which flags were used** (e.g., `check --json` — only flag presence, never flag values)
- **Exit code** (0, 1, 2, or 130) and **execution duration** (milliseconds), plus a short **outcome** tag (`success`, `user_error`, `internal_error`, `cancelled`)
- **Environment**: OS, architecture, Bun version, Archgate version, CI detection (including provider: GitHub Actions / GitLab CI / CircleCI / etc.), TTY detection, WSL detection, shell (bash, zsh, pwsh...), and locale
- **Install context**: how the CLI was installed (binary, proto, local dev dependency, or global package manager)
- **Project context**: whether an Archgate project exists in the current directory, how many ADRs it has, how many have automated rules, and how many distinct ADR domains are used
- **Repo context** (non-identifying): whether the current directory is a git repository, the host bucket (`github` / `gitlab` / `bitbucket` / `azure-devops` / `other`), a **hashed `repo_id`** (SHA-256 of the normalized remote URL, truncated to 16 hex characters — not reversible), and the default branch name
- **Coarse location**: country and region (resolved server-side from your IP, then the IP is discarded — see [IP anonymization](#ip-anonymization))
- **Anonymous install ID**: a random UUID generated on first run — not derived from any personal data

In addition to the general command lifecycle events (`command_executed` / `command_completed`), specific commands send enriched outcome events:

- **`check`**: aggregate rule counts (total, passed, failed, warnings, errors), output format used, whether filters were applied, files scanned, load duration, check duration — no file paths or violation content
- **`init`**: editor choice, whether the plugin was installed, whether the project already existed. A separate one-time `project_initialized` event is emitted with the repo host bucket, `repo_is_git`, and a `repo_public` flag. For repos confirmed public on GitHub / GitLab / Bitbucket, this event also carries the remote URL, owner, and repo name — see [Repo identity](#repo-identity). Private and self-hosted repos never have identity shared.
- **`upgrade`**: version transition (from → to), install method, success/failure, and an optional failure reason
- **`login`**: subcommand used (login, logout, refresh, status), success/failure, and a failure bucket (`network`, `tls`, `denied`, `other`) when it fails
- **`telemetry_preference_changed`**: fires once when you enable or disable telemetry, so we can understand opt-out rates

## Repo identity

Archgate sends a **hashed** `repo_id` with every event so we can count distinct repositories using the CLI without learning their names. The raw remote URL, owner, and repository name are **not** included in the common event stream.

On `archgate init`, a one-time `project_initialized` event is emitted. If — and only if — the repository is confirmed **public** on GitHub, GitLab, Bitbucket, or Azure DevOps (via an unauthenticated API probe against the host), that event additionally includes `remote_url`, `repo_owner`, and `repo_name`. This lets us see which public repositories are adopting Archgate without ever exposing private ones.

**What's never shared:**

- Private repositories (API probe returns 404, 401, or `private: true`)
- Self-hosted Git hosts (the probe skips these entirely)
- Repositories where the probe times out, is rate-limited, or otherwise fails to return a definitive public answer

**Don't want the event at all?** Disable telemetry entirely — the whole `project_initialized` event is then suppressed along with everything else:

```bash
# Per-shell / per-invocation
export ARCHGATE_TELEMETRY=0

# Or persistently
archgate telemetry disable
```

See [How to opt out](#how-to-opt-out) below for the full details.

### Error tracking (Sentry)

When the CLI crashes (exit code 2), we send:

- **Error type, message, and stack trace** (file paths are stripped to relative paths like `src/cli.ts`)
- **Runtime context**: OS, architecture, Bun version, Archgate version
- **Anonymous install ID** (same random UUID as analytics)

## What we do NOT collect

- **No personal information**: no usernames, emails, or IP addresses. GitHub / GitLab / Bitbucket owner/repository names are only sent on the one-time `project_initialized` event for repositories that are confirmed public by their host — see [Repo identity](#repo-identity). Private and self-hosted repos never have identity shared.
- **No file content**: no ADR content, source code, or file paths
- **No prompt or AI context**: nothing from agent interactions, prompts, or AI-generated content
- **No flag values**: we record that `--json` was used, not what the JSON output contained
- **No network activity**: no URLs, API keys, or tokens

## IP anonymization

Archgate uses PostHog's built-in IP anonymization:

1. Your CLI sends an event to PostHog with `$ip: null`
2. PostHog resolves your IP to a **country and region** (e.g., "US", "California") server-side
3. The IP address is then **discarded** — it is never stored in PostHog

For Sentry error tracking, the project has **"Prevent Storing of IP Addresses"** enabled, so IPs are stripped before storage.

## How to opt out

You can disable all telemetry (both analytics and error tracking) in two ways:

### Environment variable

```bash
export ARCHGATE_TELEMETRY=0
```

Accepted values: `0`, `false`, `no`, `off` (case-insensitive).

Add this to your shell profile (`.bashrc`, `.zshrc`, etc.) to disable permanently.

### CLI command

```bash
archgate telemetry disable
```

To re-enable:

```bash
archgate telemetry enable
```

To check current status:

```bash
archgate telemetry status
```

The environment variable takes precedence over the CLI setting. If `ARCHGATE_TELEMETRY=0` is set, telemetry is disabled regardless of the CLI config.

## Legal basis

Archgate CLI telemetry operates on an **opt-out basis** under GDPR Article 6(1)(f) and LGPD Article 7, IX c/c Article 10 — legitimate interests of the controller. We have published a formal [Legitimate Interest Assessment](https://archgate.dev/legitimate-interest-assessment) documenting why this is proportionate and lawful.

In summary: the data is anonymous (random UUID, no PII), the impact on users is minimal, robust safeguards are in place (IP anonymization, EU storage, limited retention, transparency), and users retain full control via an easy, permanent opt-out.

## Where data is stored

| Service       | Data                              | Region         | Retention           |
| ------------- | --------------------------------- | -------------- | ------------------- |
| PostHog Cloud | Anonymous usage analytics         | EU (Frankfurt) | 1 year              |
| Sentry Cloud  | Crash reports                     | EU (Frankfurt) | 90 days             |
| Local config  | Telemetry preference + install ID | Your machine   | Until you delete it |

Analytics events are routed through `n.archgate.dev` and error reports through `s.archgate.dev`. These are transparent reverse proxies operated by Dasolve AS on Cloudflare infrastructure — they forward requests without logging, storing, or inspecting payloads.

## Your rights

- **Right of access**: Request a copy of all data associated with your install ID. Email [privacy@archgate.dev](mailto:privacy@archgate.dev) with your install ID (found via `archgate telemetry status` or in `~/.archgate/config.json`). Response within 30 days.
- **Right to erasure**: Request deletion of historical analytics and crash data. Disabling telemetry stops future collection but does not delete past events. Email [privacy@archgate.dev](mailto:privacy@archgate.dev) with your install ID for deletion.
- **Right to object**: Disable telemetry at any time via `archgate telemetry disable` or `ARCHGATE_TELEMETRY=0`.
- **Right to lodge a complaint**: Contact the Norwegian Data Protection Authority ([Datatilsynet](https://www.datatilsynet.no)) or, for Brazilian users, the ANPD ([www.gov.br/anpd](https://www.gov.br/anpd)).

**Data controller:** Dasolve AS (Org.nr 936 035 019), Lillogata 5P, 0484 Oslo, Norway. Contact: [privacy@archgate.dev](mailto:privacy@archgate.dev).

**Brazilian users (LGPD):** For LGPD-specific rights (Art. 18), international transfer details (Art. 33), and ANPD contact information, see the [Portuguese privacy policy](https://archgate.dev/pt-br/privacy-policy).

## Open source

The telemetry implementation is fully open source. You can inspect exactly what data is collected by reading:

- [`src/helpers/telemetry.ts`](https://github.com/archgate/cli/blob/main/src/helpers/telemetry.ts) — PostHog event tracking
- [`src/helpers/sentry.ts`](https://github.com/archgate/cli/blob/main/src/helpers/sentry.ts) — Sentry error capture
- [`src/helpers/telemetry-config.ts`](https://github.com/archgate/cli/blob/main/src/helpers/telemetry-config.ts) — Config and opt-out logic

---

## Examples: clean-architecture-layers

Source: https://cli.archgate.dev/examples/clean-architecture-layers/

Enforce dependency direction in clean architecture — inner layers must not reference outer layers.

## Rule details

Clean architecture mandates that dependencies point inward: API → Application → Domain. The Domain layer must have zero external dependencies, the Application layer must not reference Infrastructure directly, and no lower layer should reference the API project. This rule checks `using` directives (C#) or `import` statements to enforce these boundaries.

The same pattern applies to any layered architecture in any language — adjust the import patterns and layer paths accordingly.

## Examples of **incorrect** code

```csharp title="Domain/Entities/User.cs"
using Microsoft.EntityFrameworkCore;        // ✗ Domain → Infrastructure
using StavangerChallenge.Infrastructure;    // ✗ Domain → Infrastructure
```

```csharp title="Application/Services/UserService.cs"
using StavangerChallenge.Infrastructure;    // ✗ Application → Infrastructure
using StavangerChallenge.API;               // ✗ Application → API
```

## Examples of **correct** code

```csharp title="Domain/Entities/User.cs"
namespace StavangerChallenge.Domain.Entities;
// No external dependencies — pure domain logic
```

```csharp title="Application/Services/UserService.cs"
using StavangerChallenge.Domain.Entities;   // ✓ Application → Domain
// Uses IRepository<T> interface, not Infrastructure directly
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "no-infrastructure-in-domain": {
      description:
        "Domain layer must not reference Infrastructure or ORM packages",
      async check(ctx) {
        const domainFiles = await ctx.glob("backend/src/**/Domain/**/*.cs");
        for (const file of domainFiles) {
          const matches = await ctx.grep(
            file,
            /using\s+(Microsoft\.EntityFrameworkCore|MyApp\.Infrastructure)/
          );
          for (const match of matches) {
            ctx.report.violation({
              message: `Domain must not reference Infrastructure: "${match.content.trim()}"`,
              file: match.file,
              line: match.line,
              fix: "Remove this using directive. Domain entities should have zero external dependencies.",
            });
          }
        }
      },
    },
    "no-infrastructure-in-application": {
      description:
        "Application layer must not reference Infrastructure directly",
      async check(ctx) {
        const appFiles = await ctx.glob("backend/src/**/Application/**/*.cs");
        for (const file of appFiles) {
          const matches = await ctx.grep(file, /using\s+MyApp\.Infrastructure/);
          for (const match of matches) {
            ctx.report.violation({
              message: `Application must not reference Infrastructure: "${match.content.trim()}"`,
              file: match.file,
              line: match.line,
              fix: "Define an interface in Application and implement it in Infrastructure.",
            });
          }
        }
      },
    },
    "no-upward-api-references": {
      description: "No layer should reference the API project",
      async check(ctx) {
        const lowerLayerPatterns = [
          "backend/src/**/Domain/**/*.cs",
          "backend/src/**/Application/**/*.cs",
          "backend/src/**/Infrastructure/**/*.cs",
        ];
        for (const pattern of lowerLayerPatterns) {
          const files = await ctx.glob(pattern);
          for (const file of files) {
            const matches = await ctx.grep(file, /using\s+MyApp\.API/);
            for (const match of matches) {
              ctx.report.violation({
                message: `Lower layers must not reference the API project: "${match.content.trim()}"`,
                file: match.file,
                line: match.line,
                fix: "Dependencies flow inward: API → Application → Domain.",
              });
            }
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

For TypeScript projects, adapt the patterns:

```typescript
// Check that domain/ does not import from infrastructure/
/import\s+.*from\s+["'].*\/infrastructure\//

// Check that no layer imports from api/
/import\s+.*from\s+["'].*\/api\//
```

## When to use it

When your project follows clean architecture, hexagonal architecture, or any layered architecture where dependency direction must be enforced.

## When not to use it

When your project does not use a layered architecture, or when layers are not organized into distinct directories.

---

## Examples: Common Rule Patterns

Source: https://cli.archgate.dev/examples/common-rule-patterns/

Browse complete, copy-pasteable rule examples organized by category. Each rule page follows a consistent format: what the rule checks, examples of incorrect and correct code, the full `.rules.ts` implementation, and guidance on when to use it.

## Dependency & Package Management

| Rule                                                    | Description                                                                  |
| ------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [no-unapproved-deps](/examples/no-unapproved-deps/)     | Restrict production dependencies to an approved allowlist                    |
| [version-catalog](/examples/version-catalog/)           | Enforce centralized version management in monorepos with `catalog:` notation |
| [monorepo-task-runner](/examples/monorepo-task-runner/) | Ban `package.json` scripts and require task runner config in every package   |

## Import & API Restrictions

| Rule                                                  | Description                                                               |
| ----------------------------------------------------- | ------------------------------------------------------------------------- |
| [no-banned-imports](/examples/no-banned-imports/)     | Prevent usage of banned libraries with a data-driven pattern list         |
| [no-banned-api](/examples/no-banned-api/)             | Ban specific runtime APIs that cause cross-platform or reliability issues |
| [wrapper-enforcement](/examples/wrapper-enforcement/) | Enforce use of a project wrapper instead of a raw platform API            |

## File Structure & Organization

| Rule                                                    | Description                                                           |
| ------------------------------------------------------- | --------------------------------------------------------------------- |
| [kebab-case-filenames](/examples/kebab-case-filenames/) | Enforce consistent file naming conventions using regex validation     |
| [no-barrel-files](/examples/no-barrel-files/)           | Detect and ban barrel files (re-export-only `index.ts`)               |
| [test-file-coverage](/examples/test-file-coverage/)     | Verify that every source file has a corresponding test file           |
| [component-pairing](/examples/component-pairing/)       | Enforce Connected/presentational component pairs with opt-out support |

## Code Quality & Output

| Rule                                                                | Description                                                        |
| ------------------------------------------------------------------- | ------------------------------------------------------------------ |
| [no-todo-comments](/examples/no-todo-comments/)                     | Flag TODO, FIXME, HACK, and XXX comments before merging            |
| [no-emoji-in-output](/examples/no-emoji-in-output/)                 | Ban emoji and raw ANSI codes in CLI output strings                 |
| [max-file-length](/examples/max-file-length/)                       | Warn when source files exceed a configurable line count            |
| [page-component-constraints](/examples/page-component-constraints/) | Enforce size limits and ban data-fetching hooks in page components |

## Database Schema

| Rule                                                      | Description                                                     |
| --------------------------------------------------------- | --------------------------------------------------------------- |
| [database-audit-fields](/examples/database-audit-fields/) | Ensure all tables include `created_at` and `updated_at` columns |

## Architecture Boundaries

| Rule                                                              | Description                                           |
| ----------------------------------------------------------------- | ----------------------------------------------------- |
| [required-export-pattern](/examples/required-export-pattern/)     | Verify files export a required function signature     |
| [openapi-routes](/examples/openapi-routes/)                       | Ensure backend routes use OpenAPI-typed definitions   |
| [clean-architecture-layers](/examples/clean-architecture-layers/) | Enforce dependency direction in layered architectures |

The editor plugins for [Claude Code](/guides/claude-code-plugin/) and [Cursor](/guides/cursor-integration/) include a Quality Manager skill that identifies recurring patterns in your codebase and proposes new rules to enforce them. [Sign up for beta access](https://plugins.archgate.dev).

---

## Examples: component-pairing

Source: https://cli.archgate.dev/examples/component-pairing/

Enforce that stateful "Connected" components have a corresponding presentational component file.

## Rule details

The container/presentational pattern separates data-fetching (Connected) components from pure UI (presentational) components. This rule checks that every `*Connected.tsx` file has a matching `*.tsx` presentational counterpart. It supports an opt-out directive (`// @no-presentational: <reason>`) for cases where a Connected component does not need a presentational pair.

## Examples of **incorrect** code

```
src/components/
  UserListConnected.tsx     ← no UserList.tsx ✗
```

## Examples of **correct** code

```
src/components/
  UserListConnected.tsx     ← fetches data, passes to UserList
  UserList.tsx              ← pure presentational component
```

Or, with an opt-out:

```typescript title="src/components/RedirectConnected.tsx"
// @no-presentational: this component only redirects, no UI to render

// ...
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "connected-wrapper-existence": {
      description:
        "Connected wrappers must have a corresponding presentational component file",
      async check(ctx) {
        const connectedFiles = await ctx.glob(
          "packages/frontend/src/components/**/*Connected.tsx"
        );

        for (const file of connectedFiles) {
          if (file.includes(".stories.") || file.includes(".test.")) continue;

          const content = await ctx.readFile(file);

          // Support opt-out directive
          if (/^\/\/\s*@no-presentational:/.test(content.trimStart())) continue;

          const presentationalFile = file.replace(/Connected\.tsx$/, ".tsx");

          try {
            await ctx.readFile(presentationalFile);
          } catch {
            ctx.report.violation({
              message: `Connected wrapper has no corresponding presentational component (expected ${presentationalFile}). Add "// @no-presentational: <reason>" to opt out.`,
              file,
              fix: `Create ${presentationalFile} as the presentational counterpart`,
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

When your frontend architecture follows the container/presentational pattern and you want to enforce that data-fetching logic is always separated from UI rendering.

## When not to use it

When your project uses a different component architecture (e.g., hooks-only, or server components), or when the pattern is applied selectively rather than universally.

---

## Examples: database-audit-fields

Source: https://cli.archgate.dev/examples/database-audit-fields/

Ensure all database tables include required audit columns.

## Rule details

Audit fields (`created_at`, `updated_at`) are essential for debugging, data governance, and sync protocols. This rule parses schema files to find table definitions, extracts each table's column block using brace-depth tracking, and checks for the presence of required columns. It works with any ORM that defines tables as function calls with object arguments (Drizzle, Prisma schema-in-code, etc.).

## Examples of **incorrect** code

```typescript title="packages/db/src/schema.ts"
export const users = sqliteTable("users", {
  id: text("id").primaryKey(),
  name: text("name").notNull(),
  email: text("email").notNull(),
  // Missing created_at and updated_at
});
```

## Examples of **correct** code

```typescript title="packages/db/src/schema.ts"
export const users = sqliteTable("users", {
  id: text("id").primaryKey(),
  name: text("name").notNull(),
  email: text("email").notNull(),
  created_at: text("created_at")
    .notNull()
    .$defaultFn(() => new Date().toISOString()),
  updated_at: text("updated_at")
    .notNull()
    .$defaultFn(() => new Date().toISOString()),
});
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "audit-fields": {
      description:
        "All database tables must have created_at and updated_at columns",
      async check(ctx) {
        const schemaFiles = await ctx.glob("packages/**/src/schema.ts");
        const TABLE_PATTERN = /sqliteTable\s*\(\s*["']([^"']+)["']/g;

        for (const file of schemaFiles) {
          const content = await ctx.readFile(file);
          let match;

          while ((match = TABLE_PATTERN.exec(content)) !== null) {
            const tableName = match[1];
            const tableStart = match.index;

            // Extract the table's column block using brace-depth tracking
            const afterMatch = content.slice(tableStart);
            const firstBrace = afterMatch.indexOf("{");
            if (firstBrace === -1) continue;

            let depth = 0;
            let tableEnd = tableStart + firstBrace;
            for (let i = firstBrace; i < afterMatch.length; i++) {
              if (afterMatch[i] === "{") depth++;
              else if (afterMatch[i] === "}") {
                depth--;
                if (depth === 0) {
                  tableEnd = tableStart + i;
                  break;
                }
              }
            }

            const tableBlock = content.slice(tableStart, tableEnd + 1);

            if (!tableBlock.includes('"created_at"')) {
              ctx.report.violation({
                message: `Table "${tableName}" is missing "created_at" column`,
                file,
                fix: 'Add created_at: text("created_at").notNull().$defaultFn(() => new Date().toISOString())',
              });
            }
            if (!tableBlock.includes('"updated_at"')) {
              ctx.report.violation({
                message: `Table "${tableName}" is missing "updated_at" column`,
                file,
                fix: 'Add updated_at: text("updated_at").notNull().$defaultFn(() => new Date().toISOString())',
              });
            }
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

When your data model requires consistent audit fields for traceability, debugging, or compliance. Adapt the `TABLE_PATTERN` regex and column names for your ORM:

```typescript
// For Drizzle with PostgreSQL
const TABLE_PATTERN = /pgTable\s*\(\s*["']([^"']+)["']/g;

// For Prisma-style definitions
const TABLE_PATTERN = /model\s+(\w+)\s*\{/g;
```

## When not to use it

When some tables intentionally omit audit fields (e.g., join tables, materialized views), or when audit fields are added automatically at the database level via triggers.

---

## Examples: kebab-case-filenames

Source: https://cli.archgate.dev/examples/kebab-case-filenames/

Enforce consistent file naming conventions across source directories.

## Rule details

Inconsistent file naming (mixing `camelCase`, `PascalCase`, `snake_case`, and `kebab-case`) makes files harder to find and causes case-sensitivity issues across operating systems. This rule validates every scoped file name against a regex pattern and suggests corrections.

## Examples of **incorrect** code

```
src/
  helpers/
    pathUtils.ts        ← camelCase
    Git_Helper.ts       ← PascalCase + snake_case
    ADRWriter.ts        ← PascalCase
```

## Examples of **correct** code

```
src/
  helpers/
    path-utils.ts
    git-helper.ts
    adr-writer.ts
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

const KEBAB_CASE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*\.(ts|tsx|js|jsx)$/;

export default {
  rules: {
    "kebab-case-filenames": {
      description: "Source files must use kebab-case naming",
      async check(ctx) {
        for (const file of ctx.scopedFiles) {
          const name = basename(file);

          // Skip test files and type declaration files
          if (name.endsWith(".test.ts") || name.endsWith(".d.ts")) continue;

          if (!KEBAB_CASE.test(name)) {
            ctx.report.violation({
              message: `File "${name}" does not follow kebab-case naming convention`,
              file,
              fix: `Rename to ${name.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase()}`,
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

When your team has standardized on a naming convention and wants to enforce it automatically. Adapt the regex for your convention:

```typescript
// PascalCase (React components)
const PASCAL_CASE = /^[A-Z][a-zA-Z0-9]*\.(ts|tsx)$/;

// camelCase
const CAMEL_CASE = /^[a-z][a-zA-Z0-9]*\.(ts|tsx|js|jsx)$/;

// snake_case (Python-style)
const SNAKE_CASE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*\.(ts|tsx|js|jsx)$/;
```

## When not to use it

When your project intentionally mixes naming conventions (e.g., PascalCase for React components and kebab-case for utilities), or when migrating a legacy codebase where bulk renames are not feasible.

---

## Examples: license-compatibility

Source: https://cli.archgate.dev/examples/license-compatibility/

Prevent copyleft or incompatible licenses from entering your dependency tree.

## Rule details

When you compile or bundle dependencies into your application, their license terms apply to the combined work. A single GPL dependency in a permissive (MIT/Apache-2.0) project can force the entire project to adopt copyleft terms. This rule checks all direct dependencies against a permissive-license allowlist.

## Examples of **incorrect** code

```json title="package.json"
{
  "dependencies": { "zod": "^3.23.0" },
  "devDependencies": { "readline-sync": "^1.4.10" }
}
```

If `readline-sync` uses GPL-3.0, it triggers a violation even as a devDependency.

## Examples of **correct** code

```json title="package.json"
{
  "dependencies": { "zod": "^3.23.0" },
  "devDependencies": { "fast-check": "^4.7.0" }
}
```

Both `zod` (MIT) and `fast-check` (MIT) are on the permissive allowlist.

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

const ALLOWED_LICENSES = new Set([
  "MIT",
  "Apache-2.0",
  "ISC",
  "BSD-2-Clause",
  "BSD-3-Clause",
  "0BSD",
  "CC0-1.0",
  "Unlicense",
  "BlueOak-1.0.0",
]);

function isAllowed(license: string | undefined): boolean {
  if (!license) return false;
  if (ALLOWED_LICENSES.has(license)) return true;

  // Handle SPDX OR expressions — at least one option must be allowed
  const normalized = license.trim().replace(/^\(/u, "").replace(/\)$/u, "");
  if (ALLOWED_LICENSES.has(normalized)) return true;

  if (normalized.includes(" OR ")) {
    return normalized.split(" OR ").some((l) => ALLOWED_LICENSES.has(l.trim()));
  }

  return false;
}

/**
 * Extract package name from a node_modules path.
 * Handles both regular and scoped (@scope/name) packages.
 */
function extractPackageName(path: string): string {
  const parts = path.replaceAll("\\", "/").split("/");
  const nmIdx = parts.lastIndexOf("node_modules");
  if (nmIdx === -1) return path;
  const afterNm = parts.slice(nmIdx + 1);
  if (afterNm[0]?.startsWith("@") && afterNm.length >= 2) {
    return `${afterNm[0]}/${afterNm[1]}`;
  }
  return afterNm[0] ?? path;
}

export default {
  rules: {
    "no-copyleft-deps": {
      description:
        "All dependencies (including transitive) must use permissive licenses",
      async check(ctx) {
        // Scan ALL packages in node_modules — direct AND transitive.
        // Brace expansion covers both regular and scoped packages.
        const pkgFiles = await ctx.glob("node_modules/{*,@*/*}/package.json");

        const depResults = await Promise.all(
          pkgFiles.map(async (pkgPath) => {
            try {
              const depPkg = (await ctx.readJSON(pkgPath)) as {
                license?: string;
              };
              return {
                dep: extractPackageName(pkgPath),
                license: depPkg.license,
              };
            } catch {
              return null;
            }
          })
        );

        for (const result of depResults) {
          if (result === null) continue;
          if (!isAllowed(result.license)) {
            ctx.report.violation({
              message: `Dependency "${result.dep}" has disallowed license: "${result.license ?? "(none)"}".`,
              file: "package.json",
              fix: `Remove "${result.dep}" or find an alternative with a permissive license.`,
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

## Customization

- **Change the allowlist**: Add or remove license identifiers based on your project's license. GPL projects can allow GPL dependencies; Apache-2.0 projects should block them.
- **Check only production deps**: Remove `devDependencies` from `allDeps` if you only care about bundled/shipped code.
- **Scan transitives**: Use `ctx.glob("node_modules/{*,@*/*}/package.json")` to scan all installed packages (including scoped) recursively, not just direct dependencies.

## When to use it

When your project uses a permissive license (MIT, Apache-2.0, ISC, BSD) and you want to prevent copyleft contamination, especially in compiled/bundled distributions.

## When not to use it

In GPL-licensed projects (where copyleft dependencies are compatible), or when you have a dedicated license-scanning SaaS tool (FOSSA, Snyk) that already gates your CI pipeline.

---

## Examples: max-file-length

Source: https://cli.archgate.dev/examples/max-file-length/

Warn when source files exceed a line count threshold.

## Rule details

Large files are harder to navigate, review, and test. This rule counts lines in each scoped file and reports a warning when the count exceeds a configurable maximum. Using `warning` severity keeps CI green while surfacing files that should be refactored.

## Examples of **incorrect** code

A file with 450 lines when the threshold is 300:

```
src/engine/runner.ts (450 lines)
```

## Examples of **correct** code

The same logic split into focused modules:

```
src/engine/runner.ts     (120 lines)
src/engine/loader.ts     (95 lines)
src/engine/reporter.ts   (85 lines)
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

const MAX_LINES = 300;

export default {
  rules: {
    "max-file-length": {
      description: `Source files should not exceed ${MAX_LINES} lines`,
      severity: "warning",
      async check(ctx) {
        const checks = ctx.scopedFiles.map(async (file) => {
          const content = await ctx.readFile(file);
          const lineCount = content.split("\n").length;
          if (lineCount > MAX_LINES) {
            ctx.report.warning({
              message: `File has ${lineCount} lines (max: ${MAX_LINES}). Consider splitting it.`,
              file,
              fix: "Extract related functions into separate modules",
            });
          }
        });
        await Promise.all(checks);
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

When you want a soft guardrail against files growing too large. Adjust `MAX_LINES` to match your team's preference (200-500 is common).

## When not to use it

When some files are legitimately large (generated code, test suites with many cases), or when you prefer other complexity metrics like cyclomatic complexity.

---

## Examples: monorepo-task-runner

Source: https://cli.archgate.dev/examples/monorepo-task-runner/

Enforce that all packages use a centralized task runner instead of `package.json` scripts.

## Rule details

In a monorepo, `package.json` scripts are local to each package and cannot express cross-package dependencies, caching, or orchestration. This rule enforces that all packages use a centralized task runner (e.g., Moon, Turborepo, Nx) by banning `scripts` in `package.json` and requiring a task runner config file (`moon.yml`, `turbo.json`, etc.) in every package.

## Examples of **incorrect** code

```json title="packages/api/package.json"
{
  "name": "@myorg/api",
  "scripts": { "build": "tsc", "test": "vitest", "lint": "eslint ." }
}
```

## Examples of **correct** code

```json title="packages/api/package.json"
{ "name": "@myorg/api" }
```

```yaml title="packages/api/moon.yml"
tasks:
  build:
    command: tsc
    inputs:
      - src/**/*
  test:
    command: vitest
    deps:
      - ~:build
  lint:
    command: eslint .
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "no-package-scripts": {
      description:
        "package.json must not have scripts — use the task runner instead",
      async check(ctx) {
        const packageJsonFiles = [
          ...(await ctx.glob("packages/*/package.json")),
          ...(await ctx.glob("packages/*/*/package.json")),
        ];

        for (const file of packageJsonFiles) {
          const pkg = (await ctx.readJSON(file)) as {
            scripts?: Record<string, string>;
          };
          if (pkg.scripts && Object.keys(pkg.scripts).length > 0) {
            ctx.report.violation({
              message: `${file}: has "scripts" field — use task runner config instead`,
              file,
              fix: 'Move scripts to the task runner config and remove "scripts" from package.json',
            });
          }
        }
      },
    },
    "task-runner-config": {
      description: "All packages must have a task runner configuration file",
      async check(ctx) {
        const packageJsonFiles = [
          ...(await ctx.glob("packages/*/package.json")),
          ...(await ctx.glob("packages/*/*/package.json")),
        ];

        for (const file of packageJsonFiles) {
          const configPath = file.replace("/package.json", "/moon.yml");
          try {
            await ctx.readFile(configPath);
          } catch {
            ctx.report.violation({
              message: `Missing task runner config: ${configPath}`,
              file: configPath,
              fix: "Create a moon.yml file with appropriate task definitions for this package",
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

In monorepos that use a centralized task runner for build orchestration. Adapt the config file check for your runner:

```typescript
// Turborepo
const configPath = file.replace("/package.json", "/turbo.json");

// Nx
const configPath = file.replace("/package.json", "/project.json");
```

## When not to use it

In single-package repositories, or in monorepos where the task runner is configured centrally (e.g., a single `turbo.json` at the root) rather than per-package.

---

## Examples: no-banned-api

Source: https://cli.archgate.dev/examples/no-banned-api/

Ban specific runtime APIs that cause cross-platform or reliability issues.

## Rule details

Some APIs work correctly on one platform but fail on another. For example, Bun's shell API (`Bun.$`) hangs on Windows due to pipe deadlocks. This rule detects multiple variants of a banned API — the direct call, the import, and destructured usage — ensuring no form slips through.

This pattern generalizes to any API you want to ban while allowing a safe alternative.

## Examples of **incorrect** code

```typescript title="src/helpers/git.ts"
// Direct usage
const result = await Bun.$`git status`;

// Import

// Destructured usage
const output = await $`ls -la`;
```

## Examples of **correct** code

```typescript title="src/helpers/git.ts"
const proc = Bun.spawn(["git", "status"], { stdout: "pipe", stderr: "pipe" });
const output = await new Response(proc.stdout).text();
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "no-bun-shell": {
      description:
        "Subprocess execution must use Bun.spawn, not Bun.$ (shell hangs on Windows)",
      async check(ctx) {
        const files = ctx.scopedFiles.filter(
          (f) => !f.includes("tests/") && !f.includes(".archgate/")
        );

        // Variant 1: Bun.$` template literal
        const bunShellMatches = await Promise.all(
          files.map((file) => ctx.grep(file, /Bun\.\$`/))
        );
        for (const fileMatches of bunShellMatches) {
          for (const m of fileMatches) {
            ctx.report.violation({
              message:
                "Do not use Bun.$ template literals — they hang on Windows. Use Bun.spawn instead.",
              file: m.file,
              line: m.line,
              fix: "Replace Bun.$`cmd args` with Bun.spawn(['cmd', 'args'], { stdout: 'pipe', stderr: 'pipe' })",
            });
          }
        }

        // Variant 2: import { $ } from "bun"
        const dollarImportMatches = await Promise.all(
          files.map((file) =>
            ctx.grep(file, /import\s*\{[^}]*\$[^}]*\}\s*from\s*["']bun["']/)
          )
        );
        for (const fileMatches of dollarImportMatches) {
          for (const m of fileMatches) {
            ctx.report.violation({
              message:
                'Do not import $ from "bun" — the shell API hangs on Windows. Use Bun.spawn instead.',
              file: m.file,
              line: m.line,
              fix: "Remove the $ import and replace shell calls with Bun.spawn",
            });
          }
        }

        // Variant 3: await $` (destructured)
        const destructuredMatches = await Promise.all(
          files.map((file) => ctx.grep(file, /await\s+\$`/))
        );
        for (const fileMatches of destructuredMatches) {
          for (const m of fileMatches) {
            ctx.report.violation({
              message:
                "Do not use $` template literals — they hang on Windows. Use Bun.spawn instead.",
              file: m.file,
              line: m.line,
              fix: "Replace $`cmd args` with Bun.spawn(['cmd', 'args'], { stdout: 'pipe', stderr: 'pipe' })",
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

When your project must run on multiple platforms and a specific API is known to fail on one of them. Also useful for banning deprecated APIs with known reliability issues.

## When not to use it

When your project targets a single platform and the banned API works reliably there.

---

## Examples: no-banned-imports

Source: https://cli.archgate.dev/examples/no-banned-imports/

Prevent usage of banned libraries and enforce recommended alternatives.

## Rule details

Teams often ban heavy or deprecated libraries in favor of lighter or native alternatives. This rule uses a data-driven configuration — an array of objects specifying the regex pattern, the library name, and the recommended alternative. Adding a new ban is a one-line change.

## Examples of **incorrect** code

```typescript title="src/utils/date.ts"

```

```typescript title="src/api/client.ts"

```

## Examples of **correct** code

```typescript title="src/utils/date.ts"

```

```typescript title="src/api/client.ts"
const response = await fetch("/api/data");
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

const BANNED_IMPORTS = [
  {
    pattern: /from\s+['"]lodash['"]/,
    name: "lodash",
    alternative: "native array methods",
  },
  {
    pattern: /from\s+['"]moment['"]/,
    name: "moment",
    alternative: "Temporal API or date-fns",
  },
  {
    pattern: /from\s+['"]axios['"]/,
    name: "axios",
    alternative: "native fetch()",
  },
];

export default {
  rules: {
    "no-banned-imports": {
      description: "Prevent usage of banned libraries",
      async check(ctx) {
        for (const banned of BANNED_IMPORTS) {
          const matches = await ctx.grepFiles(banned.pattern, "src/**/*.ts");
          for (const match of matches) {
            ctx.report.violation({
              message: `Banned import: "${banned.name}" is not allowed. Use ${banned.alternative} instead.`,
              file: match.file,
              line: match.line,
              fix: `Replace ${banned.name} with ${banned.alternative}`,
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

When your team has standardized on specific libraries and wants to prevent drift toward alternatives. Common bans include lodash (native methods), moment (date-fns or Temporal), and axios (native fetch).

## When not to use it

When your project has no preference between libraries, or when the banned library is still in active migration and some usage is expected temporarily.

---

## Examples: no-barrel-files

Source: https://cli.archgate.dev/examples/no-barrel-files/

Detect and ban barrel files — `index.ts` files that contain only re-exports and no logic.

## Rule details

Barrel files (re-export-only `index.ts`) obscure where code actually lives, hurt tree-shaking, create circular dependency risks, and slow down IDE navigation. This rule uses a custom analysis function to determine whether an `index.ts` file is a pure re-export barrel by inspecting every non-comment, non-blank line.

## Examples of **incorrect** code

```typescript title="src/helpers/index.ts"
export { logInfo, logError } from "./log";
export { resolvePaths } from "./paths";
export type { PathConfig } from "./paths";
```

A file that only re-exports symbols from other modules is a barrel file.

## Examples of **correct** code

```typescript title="src/helpers/index.ts"
export { logInfo, logError } from "./log";
export { resolvePaths } from "./paths";

// This file has its own logic, so it is not a barrel
export function getHelperVersion(): string {
  return "1.0.0";
}
```

Or better — delete `index.ts` entirely and import directly:

```typescript

```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

function isBarrelFile(content: string): boolean {
  const lines = content
    .split("\n")
    .map((l) => l.trim())
    .filter(
      (l) =>
        l !== "" &&
        !l.startsWith("//") &&
        !l.startsWith("/*") &&
        !l.startsWith("*")
    );

  if (lines.length === 0) return false;

  return lines.every(
    (line) =>
      line.startsWith("export ") ||
      line.startsWith("export{") ||
      line.startsWith("import ") ||
      line.startsWith("} from") ||
      line.startsWith("type ") ||
      /^[A-Za-z_$,\s]+$/.test(line) ||
      line === "}" ||
      line === "};"
  );
}

export default {
  rules: {
    "no-barrel-files": {
      description: "index.ts files must not be pure re-export barrels",
      async check(ctx) {
        const indexFiles = ctx.scopedFiles.filter((f) =>
          f.endsWith("/index.ts")
        );

        const checks = indexFiles.map(async (file) => {
          const content = await ctx.readFile(file);
          if (isBarrelFile(content)) {
            ctx.report.violation({
              message: `Barrel file detected: ${file} contains only re-exports and no logic.`,
              file,
              fix: "Delete this barrel file and update imports to point directly to the source module",
            });
          }
        });

        await Promise.all(checks);
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

When you want to enforce direct imports and avoid the indirection that barrel files introduce. Especially valuable in large codebases where barrel files cause slow IDE performance and make dependency graphs harder to reason about.

## When not to use it

When your project intentionally uses barrel files as a public API boundary (e.g., a library that exports a curated API from `index.ts`).

---

## Examples: no-emoji-in-output

Source: https://cli.archgate.dev/examples/no-emoji-in-output/

Ban emoji characters in CLI output strings.

## Rule details

Emoji render inconsistently across terminals, break alignment in monospace output, and cause issues with screen readers and CI log parsers. This rule uses Unicode range regex to detect emoji characters and a secondary check to ensure they appear inside string literals (not comments or variable names).

The rule also checks for raw ANSI escape codes, enforcing the use of `styleText()` from `node:util` for terminal formatting.

## Examples of **incorrect** code

```typescript title="src/commands/check.ts"
console.log("✅ All checks passed!");
console.log("❌ Validation failed");
console.log("\x1b[32mSuccess\x1b[0m"); // raw ANSI
```

## Examples of **correct** code

```typescript title="src/commands/check.ts"

console.log("All checks passed");
console.log("Validation failed");
console.log(styleText("green", "Success"));
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

const EMOJI_PATTERN =
  /[\u{1F600}-\u{1F64F}\u{1F300}-\u{1F5FF}\u{1F680}-\u{1F6FF}\u{1F900}-\u{1F9FF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}]/u;
const EMOJI_IN_STRING =
  /["'`].*[\u{1F600}-\u{1F64F}\u{1F300}-\u{1F5FF}\u{1F680}-\u{1F6FF}\u{1F900}-\u{1F9FF}\u{2600}-\u{26FF}\u{2700}-\u{27BF}].*["'`]/u;

export default {
  rules: {
    "no-emoji-in-output": {
      description: "CLI output must not contain emoji characters",
      async check(ctx) {
        const files = ctx.scopedFiles.filter(
          (f) => !f.includes("tests/") && !f.includes(".archgate/")
        );
        const matches = await Promise.all(
          files.map((file) => ctx.grep(file, EMOJI_PATTERN))
        );
        for (const fileMatches of matches) {
          for (const m of fileMatches) {
            if (EMOJI_IN_STRING.test(m.content)) {
              ctx.report.violation({
                message: "Do not use emoji in CLI output strings",
                file: m.file,
                line: m.line,
                fix: "Remove emoji from output strings",
              });
            }
          }
        }
      },
    },
    "use-style-text": {
      description: "Use styleText from node:util instead of raw ANSI codes",
      async check(ctx) {
        const files = ctx.scopedFiles.filter(
          (f) => !f.includes("tests/") && !f.includes(".archgate/")
        );
        const matches = await Promise.all(
          files.map((file) => ctx.grep(file, /\\u001b\[|\\x1b\[|\\033\[/))
        );
        for (const fileMatches of matches) {
          for (const m of fileMatches) {
            ctx.report.violation({
              message:
                "Use styleText() from node:util instead of raw ANSI escape codes",
              file: m.file,
              line: m.line,
              fix: "Import { styleText } from 'node:util' and use styleText(style, text)",
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

In CLI tools where output consistency across terminals matters, or when accessibility is a priority.

## When not to use it

In web applications or tools where emoji are part of the expected UI, or when your output is always consumed by humans in modern terminals.

---

## Examples: no-todo-comments

Source: https://cli.archgate.dev/examples/no-todo-comments/

Flag `TODO`, `FIXME`, `HACK`, and `XXX` comments so they are resolved before merging.

## Rule details

TODO comments are useful during development but should not accumulate in the main branch. This rule uses `ctx.grepFiles` to scan all source files for common task-marker comments. It uses `warning` severity so it does not block CI, but makes the comments visible in every check run.

## Examples of **incorrect** code

```typescript title="src/helpers/git.ts"
// TODO: handle merge conflicts
// FIXME: this breaks on Windows
// HACK: workaround for upstream bug
// XXX: revisit this logic
```

## Examples of **correct** code

```typescript title="src/helpers/git.ts"
// Proper implementation with no deferred work
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "no-todo-comments": {
      description: "TODO and FIXME comments should be resolved before merging",
      severity: "warning",
      async check(ctx) {
        const matches = await ctx.grepFiles(
          /\/\/\s*(TODO|FIXME|HACK|XXX):/i,
          "src/**/*.ts"
        );
        for (const match of matches) {
          ctx.report.warning({
            message: `${match.content.trim()} — resolve before merging`,
            file: match.file,
            line: match.line,
          });
        }
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

When you want visibility into deferred work and want to prevent TODO comments from accumulating over time. Change severity to `"error"` and use `ctx.report.violation()` to make it a hard blocker.

## When not to use it

When TODO comments are intentional documentation (e.g., tracked by a separate tool that creates issues from TODO comments).

---

## Examples: no-unapproved-deps

Source: https://cli.archgate.dev/examples/no-unapproved-deps/

Restrict production dependencies to an approved allowlist.

## Rule details

Large dependency trees increase supply-chain risk and bloat bundle sizes. This rule reads `package.json` and reports any production dependency that is not on an explicit allowlist. Dev dependencies are not checked.

## Examples of **incorrect** code

```json title="package.json"
{ "dependencies": { "zod": "^3.23.0", "chalk": "^5.3.0" } }
```

If only `zod` is on the approved list, `chalk` triggers a violation.

## Examples of **correct** code

```json title="package.json"
{
  "dependencies": { "zod": "^3.23.0" },
  "devDependencies": { "chalk": "^5.3.0" }
}
```

All production dependencies are on the approved list. Libraries needed only at build time are in `devDependencies`.

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

const APPROVED_DEPS = [
  "@commander-js/extra-typings",
  "inquirer",
  "@modelcontextprotocol/sdk",
  "zod",
];

export default {
  rules: {
    "no-unapproved-deps": {
      description: "Production dependencies must be on the approved list",
      async check(ctx) {
        let pkg: { dependencies?: Record<string, string> };
        try {
          pkg = (await ctx.readJSON("package.json")) as typeof pkg;
        } catch {
          return; // No package.json — nothing to check
        }

        const deps = Object.keys(pkg.dependencies ?? {});
        for (const dep of deps) {
          if (!APPROVED_DEPS.includes(dep)) {
            ctx.report.violation({
              message: `Unapproved production dependency: "${dep}". Approved: ${APPROVED_DEPS.join(", ")}`,
              file: "package.json",
              fix: `Either add "${dep}" to the approved list in the ADR or move it to devDependencies`,
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

When your team has an explicit dependency governance policy and wants to prevent unapproved packages from entering the production bundle.

## When not to use it

In early-stage projects where the dependency list is still evolving rapidly, or when dependency governance is handled by a separate tool like Socket or Snyk.

---

## Examples: openapi-routes

Source: https://cli.archgate.dev/examples/openapi-routes/

Ensure all backend route files use OpenAPI-typed route definitions.

## Rule details

When a backend framework supports OpenAPI integration (e.g., `@hono/zod-openapi`), raw HTTP method handlers (`.get()`, `.post()`) bypass schema validation and documentation generation. This rule checks that route files import the OpenAPI integration and use `.openapi()` instead of raw methods.

## Examples of **incorrect** code

```typescript title="packages/backend/src/routes/users.ts"

const app = new Hono();

app.get("/users", async (c) => {
  // No OpenAPI schema, no auto-generated docs
  return c.json(await getUsers());
});
```

## Examples of **correct** code

```typescript title="packages/backend/src/routes/users.ts"

const route = createRoute({
  method: "get",
  path: "/users",
  responses: {
    200: {
      content: { "application/json": { schema: UserListSchema } },
      description: "List of users",
    },
  },
});

app.openapi(route, async (c) => {
  return c.json(await getUsers());
});
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "openapi-route-completeness": {
      description:
        "All backend routes must use @hono/zod-openapi, not raw HTTP methods",
      async check(ctx) {
        const routeFiles = await ctx.glob("packages/backend/src/routes/*.ts");

        for (const file of routeFiles) {
          if (file.includes(".test.") || file.includes(".spec.")) continue;

          const content = await ctx.readFile(file);

          const importsOpenApi = /from\s+["']@hono\/zod-openapi["']/.test(
            content
          );
          const hasRawMethods = /\.(?:get|post|put|delete|patch)\s*\(/.test(
            content
          );
          const hasOpenApiCalls = /\.openapi\s*\(/.test(content);

          if (!importsOpenApi && hasRawMethods) {
            ctx.report.violation({
              message: `Route file uses raw HTTP methods without importing @hono/zod-openapi`,
              file,
              fix: "Import from @hono/zod-openapi and use .openapi() instead of raw .get()/.post()",
            });
          }

          if (importsOpenApi && hasRawMethods && !hasOpenApiCalls) {
            ctx.report.violation({
              message: `Route file imports @hono/zod-openapi but uses raw HTTP methods instead of .openapi()`,
              file,
              fix: "Replace raw .get()/.post() calls with .openapi() route definitions",
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

When your backend framework supports OpenAPI integration and you want to ensure all routes are documented and schema-validated. Adapt the import pattern and method detection for your framework:

```typescript
// For Express with express-openapi-validator
/from\s+["']express-openapi-validator["']/

// For Fastify with @fastify/swagger
/from\s+["']@fastify\/swagger["']/
```

## When not to use it

When not all routes require OpenAPI documentation (e.g., internal health checks, metrics endpoints), or when OpenAPI specs are maintained separately from route code.

---

## Examples: page-component-constraints

Source: https://cli.archgate.dev/examples/page-component-constraints/

Enforce that page components are thin layout wrappers — small in size and free of data-fetching logic.

## Rule details

In frontend architectures that separate routing from logic, page components should only compose layout and delegate data-fetching to Connected components. This rule enforces two constraints in a single rules file:

1. **Size limit** — Page components must stay under a configurable line count (default: 75 lines).
2. **No data hooks** — Page components must not use `useState`, `useQuery`, `useMutation`, or other data-fetching hooks directly.

## Examples of **incorrect** code

```tsx title="src/pages/DashboardPage.tsx"

export default function DashboardPage() {
  const [filter, setFilter] = useState(""); // ✗ state hook
  const { data } = useQuery({ queryKey: ["dashboard"] }); // ✗ data hook
  // ... 120 lines of layout + logic
}
```

## Examples of **correct** code

```tsx title="src/pages/DashboardPage.tsx"

export default function DashboardPage() {
  return (
    <div className="flex">
      
      
    </div>
  );
}
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

const PAGE_MAX_LINES = 75;

export default {
  rules: {
    "page-max-lines": {
      description: `Page components must be under ${PAGE_MAX_LINES} lines`,
      async check(ctx) {
        const pageFiles = await ctx.glob("src/pages/*Page.tsx");

        for (const file of pageFiles) {
          if (file.includes(".test.")) continue;

          const content = await ctx.readFile(file);
          const lineCount = content.split("\n").length;

          if (lineCount > PAGE_MAX_LINES) {
            ctx.report.violation({
              message: `Page component has ${lineCount} lines (max ${PAGE_MAX_LINES}). Extract logic to Connected components.`,
              file,
              fix: "Move data-fetching and business logic to Connected components",
            });
          }
        }
      },
    },
    "page-no-data-hooks": {
      description: "Page components must not use data-fetching or state hooks",
      async check(ctx) {
        const pageFiles = await ctx.glob("src/pages/*Page.tsx");

        const FORBIDDEN_HOOKS =
          /\b(useState|useForm|useQuery|useMutation|useSuspenseQuery|useInfiniteQuery)\s*[<(]/g;

        const ALLOWED_HOOKS = new Set([
          "useParams",
          "useNavigate",
          "useRouter",
          "useMatch",
          "useLocation",
          "useSearch",
        ]);

        for (const file of pageFiles) {
          if (file.includes(".test.")) continue;

          const content = await ctx.readFile(file);

          let match;
          while ((match = FORBIDDEN_HOOKS.exec(content)) !== null) {
            ctx.report.violation({
              message: `Page component uses "${match[1]}" hook. Extract to a Connected component.`,
              file,
              fix: `Move the "${match[1]}" hook to a Connected component`,
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

When your frontend architecture follows the page/container/presentational pattern and you want to enforce that pages remain thin routing endpoints. Adjust `PAGE_MAX_LINES` and the hook lists for your framework.

## When not to use it

When pages are expected to contain logic (e.g., in Next.js server components where data fetching in the page is idiomatic), or when your project does not follow this architectural pattern.

---

## Examples: required-export-pattern

Source: https://cli.archgate.dev/examples/required-export-pattern/

Verify that files in a specific directory export a required function signature.

## Rule details

Convention-based architectures (CLI command files, route handlers, plugin modules) often require each file to export a function with a specific naming pattern. This rule scans scoped files for a required export and reports any file that does not match. It uses `Promise.all()` to check files in parallel for performance.

## Examples of **incorrect** code

```typescript title="src/commands/deploy.ts"
// Missing the required register*Command export
export function deploy() {
  // ...
}
```

## Examples of **correct** code

```typescript title="src/commands/deploy.ts"

export function registerDeployCommand(program: Command) {
  program
    .command("deploy")
    .description("Deploy the application")
    .action(() => {
      // ...
    });
}
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "register-function-export": {
      description: "Command files must export a register*Command function",
      async check(ctx) {
        const files = ctx.scopedFiles.filter((f) => !f.endsWith("index.ts"));
        const checks = files.map(async (file) => {
          const content = await ctx.readFile(file);
          if (!/export\s+function\s+register\w+Command/.test(content)) {
            ctx.report.violation({
              message: "Command file must export a register*Command function",
              file,
            });
          }
        });
        await Promise.all(checks);
      },
    },
  },
} satisfies RuleSet;
```

Adapt the pattern for other conventions:

```typescript
// Express/Hono route handlers
/export\s+default\s+.*Router/

// React page components
/export\s+default\s+function\s+\w+Page/

// Plugin modules
/export\s+const\s+plugin\s*[:=]/
```

## When to use it

When your architecture requires a specific export pattern from files in a directory. Pair this with the ADR's `files` frontmatter field to scope it to the right directory.

## When not to use it

When the directory contains mixed file types that do not all need to follow the same export pattern.

---

## Examples: spdx-license-headers

Source: https://cli.archgate.dev/examples/spdx-license-headers/

Ensure every source file declares its license with a machine-readable SPDX identifier.

## Rule details

Open-source projects benefit from per-file license declarations — they survive file extraction, bundling, and copy-paste scenarios where the root LICENSE file is not present. This rule verifies that every TypeScript source file starts with the standard SPDX header comment.

## Examples of **incorrect** code

```typescript title="src/helpers/utils.ts"

export function resolvePath(base: string, rel: string): string {
  return join(base, rel);
}
```

File is missing the SPDX license identifier header.

## Examples of **correct** code

```typescript title="src/helpers/utils.ts"
// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Archgate

export function resolvePath(base: string, rel: string): string {
  return join(base, rel);
}
```

For files with a shebang:

```typescript title="src/cli.ts"
#!/usr/bin/env bun
// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Archgate

```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "spdx-header-present": {
      description:
        "All TypeScript source files must have an SPDX-License-Identifier header",
      async check(ctx) {
        const results = await Promise.all(
          ctx.scopedFiles.map(async (file) => {
            const content = await ctx.readFile(file);
            return { file, content };
          })
        );

        for (const { file, content } of results) {
          if (content === null) continue;

          // Check first 5 lines for the SPDX identifier (allows for shebang)
          const lines = content.split("\n").slice(0, 5);
          const hasSpdx = lines.some((line) =>
            line.includes("SPDX-License-Identifier: Apache-2.0")
          );

          if (!hasSpdx) {
            ctx.report.violation({
              message: "Missing SPDX-License-Identifier header.",
              file,
              line: 1,
              fix: 'Add "// SPDX-License-Identifier: Apache-2.0" as the first line of the file',
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

## Customization

- **Change the license**: Replace `Apache-2.0` with your project's SPDX identifier (e.g., `MIT`, `BSD-3-Clause`)
- **Change the scope**: Adjust the `files` glob in the ADR frontmatter to match your source directories
- **Add copyright check**: Extend the rule to also verify the copyright line format

## When to use it

When your project is open-source and you want unambiguous per-file license declarations that are recognized by compliance scanners (FOSSA, Snyk, Black Duck, npm license-checker).

## When not to use it

In proprietary/closed-source projects where all files are implicitly "all rights reserved," or when your organization uses a different license-declaration mechanism like REUSE 3.0 `.dep5` files.

---

## Examples: test-file-coverage

Source: https://cli.archgate.dev/examples/test-file-coverage/

Verify that every source file has a corresponding test file.

## Rule details

Untested code is a liability. This rule enforces a structural convention: for every file in `src/`, a matching `.test.ts` file must exist in `tests/`. It uses `ctx.glob` to discover existing test files, builds a lookup set for fast matching, and reports any source file without a counterpart.

## Examples of **incorrect** code

```
src/
  helpers/
    log.ts          ← has a test ✓
    paths.ts        ← no test file ✗
tests/
  helpers/
    log.test.ts
```

## Examples of **correct** code

```
src/
  helpers/
    log.ts
    paths.ts
tests/
  helpers/
    log.test.ts
    paths.test.ts
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "test-file-exists": {
      description: "Every source file should have a corresponding test file",
      severity: "warning",
      async check(ctx) {
        for (const file of ctx.scopedFiles) {
          const rel = relative(ctx.projectRoot, file);
          const testPath = rel
            .replace(/^src\//, "tests/")
            .replace(/\.ts$/, ".test.ts");
          const testFiles = await ctx.glob(testPath);
          if (testFiles.length === 0) {
            ctx.report.warning({
              message: `No test file found at ${testPath}`,
              file,
              fix: `Create a test file at ${testPath}`,
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

To adapt for projects that colocate tests next to source files:

```typescript
const testPath = rel.replace(/\.ts$/, ".test.ts");
// src/helpers/log.ts → src/helpers/log.test.ts
```

## When to use it

When your team follows a convention that every source module must have a corresponding test file, and you want to catch missing tests during code review.

## When not to use it

When test coverage is tracked by other means (e.g., coverage thresholds in CI), or when some source files genuinely do not need tests (type-only files, constants).

---

## Examples: version-catalog

Source: https://cli.archgate.dev/examples/version-catalog/

Enforce centralized version management in monorepos by requiring `catalog:` or `workspace:` notation for all dependencies.

## Rule details

In monorepos with many packages, duplicating version strings across `package.json` files leads to version drift and upgrade pain. This rule ensures every dependency reference uses `catalog:` (resolved from a central catalog in the root `package.json`) or `workspace:` (for internal packages), never a raw semver string.

The rule has two checks: `catalog-usage` verifies all dependencies use the correct notation, and `catalog-completeness` verifies that every `catalog:` reference resolves to an actual entry in the root catalog.

## Examples of **incorrect** code

```json title="packages/api/package.json"
{ "dependencies": { "zod": "^3.23.0", "hono": "^4.0.0" } }
```

Raw semver strings bypass the central catalog and will diverge across packages.

## Examples of **correct** code

```json title="packages/api/package.json"
{
  "dependencies": {
    "zod": "catalog:",
    "hono": "catalog:",
    "@myorg/shared": "workspace:*"
  }
}
```

```json title="package.json (root)"
{ "catalog": { "zod": "^3.23.0", "hono": "^4.0.0" } }
```

All versions are managed centrally. Upgrading `zod` requires changing only the root catalog.

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "catalog-usage": {
      description:
        'All workspace dependencies must use "catalog:" or "workspace:" notation',
      async check(ctx) {
        const packageJsonFiles = [
          ...(await ctx.glob("packages/*/package.json")),
          ...(await ctx.glob("packages/*/*/package.json")),
        ];

        for (const file of packageJsonFiles) {
          const pkg = (await ctx.readJSON(file)) as Record<string, unknown>;
          for (const depType of [
            "dependencies",
            "devDependencies",
            "peerDependencies",
          ]) {
            const deps = pkg[depType] as Record<string, string> | undefined;
            if (!deps) continue;

            for (const [name, version] of Object.entries(deps)) {
              if (
                typeof version === "string" &&
                !version.startsWith("catalog:") &&
                !version.startsWith("workspace:")
              ) {
                ctx.report.violation({
                  message: `${file}: ${depType}.${name} uses "${version}" instead of "catalog:" or "workspace:"`,
                  file,
                  fix: `Change to "catalog:" and ensure the package is listed in root package.json catalog`,
                });
              }
            }
          }
        }
      },
    },
    "catalog-completeness": {
      description:
        "All catalog: references must resolve to entries in root package.json catalog",
      async check(ctx) {
        const rootPkg = (await ctx.readJSON("package.json")) as Record<
          string,
          unknown
        >;
        const catalog = (rootPkg.catalog ?? {}) as Record<string, string>;
        const catalogKeys = new Set(Object.keys(catalog));

        const packageJsonFiles = [
          ...(await ctx.glob("packages/*/package.json")),
          ...(await ctx.glob("packages/*/*/package.json")),
        ];

        for (const file of packageJsonFiles) {
          const pkg = (await ctx.readJSON(file)) as Record<string, unknown>;
          for (const depType of [
            "dependencies",
            "devDependencies",
            "peerDependencies",
          ]) {
            const deps = pkg[depType] as Record<string, string> | undefined;
            if (!deps) continue;

            for (const [name, version] of Object.entries(deps)) {
              if (
                typeof version !== "string" ||
                !version.startsWith("catalog:")
              )
                continue;

              const catalogRef =
                version === "catalog:"
                  ? name
                  : version.slice("catalog:".length);

              if (!catalogKeys.has(catalogRef)) {
                ctx.report.violation({
                  message: `${file}: ${depType}.${name} references catalog:${catalogRef} but it is not in root catalog`,
                  file,
                  fix: `Add "${catalogRef}" to the catalog section in the root package.json`,
                });
              }
            }
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

In monorepos where multiple packages share dependencies and you want a single source of truth for versions (e.g., Bun workspaces with catalog support, or similar setups).

## When not to use it

In single-package repositories or monorepos that use a different version management strategy like Renovate's group updates.

---

## Examples: wrapper-enforcement

Source: https://cli.archgate.dev/examples/wrapper-enforcement/

Enforce use of a project wrapper instead of a raw platform API.

## Rule details

When a project provides a helper that normalizes a low-level API (e.g., a `platform.ts` helper wrapping `process.platform`), direct usage of the raw API should be banned everywhere except in the wrapper itself. This rule scans scoped files for the raw API call while automatically excluding the helper file and non-production code.

## Examples of **incorrect** code

```typescript title="src/commands/build.ts"
if (process.platform === "win32") {
  // Windows-specific logic
}
```

## Examples of **correct** code

```typescript title="src/commands/build.ts"

if (isWindows()) {
  // Windows-specific logic
}
```

## Rule implementation

```typescript
/// <reference path="../rules.d.ts" />

export default {
  rules: {
    "no-direct-process-platform": {
      description:
        "Platform detection must use src/helpers/platform.ts, not process.platform directly",
      async check(ctx) {
        const files = ctx.scopedFiles.filter(
          (f) =>
            !f.includes("tests/") &&
            !f.includes(".archgate/") &&
            !f.endsWith("src/helpers/platform.ts") // Exclude the wrapper itself
        );

        const matches = await Promise.all(
          files.map((file) => ctx.grep(file, /process\.platform/))
        );
        for (const fileMatches of matches) {
          for (const m of fileMatches) {
            ctx.report.violation({
              message:
                "Do not access process.platform directly — use isWindows(), isMacOS(), or isLinux() from src/helpers/platform.ts instead.",
              file: m.file,
              line: m.line,
              fix: 'Import { isWindows } from "../helpers/platform" and use it instead of process.platform',
            });
          }
        }
      },
    },
  },
} satisfies RuleSet;
```

## When to use it

When your project has a wrapper or helper module that normalizes a raw API and you want to prevent direct access to the underlying API. Common examples:

- `platform.ts` wrapping `process.platform`
- `logger.ts` wrapping `console.log` / `console.error`
- `fs.ts` wrapping `node:fs` with project-specific defaults
- `env.ts` wrapping `process.env` with typed accessors

## When not to use it

When the raw API is simple enough that a wrapper adds no value, or when the wrapper has not yet been adopted across the codebase (consider using `warning` severity during migration).

---