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"
}

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.

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.