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 (when custom domains are registered) or when you manually add configuration. It lives inside the .archgate/ directory at your project root.

Schema

{
  "domains": { "security": "SEC", "compliance": "COMP" },
  "paths": { "adrs": "docs/adrs", "rules": "docs/adrs" }
}

domains

Custom domain-to-prefix mappings. See 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.

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:

{ "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.