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

{
  "domains": { "security": "SEC", "compliance": "COMP" },
  "paths": { "adrs": "docs/adrs", "rules": "docs/adrs" },
  "baseBranch": "main",
  "strict": true
}

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.

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:

{ "baseBranch": "main" }

See archgate check — Changed files detection for the full resolution priority.

strict

Project-wide default for --strict, supported by archgate check, archgate review-context, and archgate adr sync. --strict escalates otherwise-advisory diagnostics into failures — see archgate check — Strict mode for exactly what each command fails on.

Type	Default	Description
boolean	false	Enables strict mode for this project by default

Resolution order is CLI flag, then this config value, then false. There is no --no-strict flag, so the CLI flag can only turn strict mode on over an absent or false config value — it cannot turn off a configured strict: true.

{ "strict": true }

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.