Configuration reference

Complete reference for .aligntrue/config.yaml configuration options.

Overview

AlignTrue uses .aligntrue/config.yaml for all configuration. The file is created during aligntrue init and uses YAML format for readability.

Location: .aligntrue/config.yaml (project root)

Format: YAML (validated against JSON Schema on load)

Mode-specific defaults: Many fields have different defaults based on mode (solo vs team vs enterprise).

Core fields

mode

Type: string

Values: "solo" | "team" | "enterprise"

Default: "solo"

Operating mode that determines default behavior for lockfiles, bundles, and auto-pull.

mode: solo # or team, enterprise

exporters

Type: array of strings

Default: ["cursor", "agents-md"]

Required: Yes (at least one)

List of exporter adapters to generate. Determines which agent files are created during sync.

exporters:
  - cursor
  - agents-md
  - vscode-mcp

See Agent Support for all 43 available exporters.

sources

Type: array of objects

Default: [{ type: "local", path: ".aligntrue/.rules.yaml" }]

Where to load rules from. Supports local files, git repos, URLs, and catalog packs.

sources:
  - type: local
    path: .aligntrue/.rules.yaml

Sync behavior

sync

Type: object

Default: Mode-specific (see below)

Controls sync direction, auto-pull, and conflict resolution.

sync:
  auto_pull: true # Auto-import from primary agent
  primary_agent: cursor # Which agent to auto-pull from
  on_conflict: accept_agent # How to resolve conflicts
  workflow_mode: native_format # Editing workflow preference
  show_diff_on_pull: true # Show diff when auto-pull runs

sync.auto_pull

Type: boolean

Default: true (solo), false (team/enterprise)

Automatically import changes from primary agent before syncing.

sync.primary_agent

Type: string

Default: Auto-detected from first importable exporter

Which agent to auto-pull from (cursor, copilot, claude-code, aider, agents-md).

sync.on_conflict

Type: string

Values: "prompt" | "keep_ir" | "accept_agent"

Default: "accept_agent" (solo), "prompt" (team/enterprise)

How to resolve conflicts when both IR and agent files are edited.

sync.workflow_mode

Type: string

Values: "auto" | "ir_source" | "native_format"

Default: "auto" (solo), "ir_source" (team/enterprise)

Preferred editing workflow:

• auto - Prompt on first conflict
• ir_source - Edit .aligntrue/.rules.yaml or AGENTS.md
• native_format - Edit agent files directly (e.g., .cursor/*.mdc)

sync.show_diff_on_pull

Type: boolean

Default: true

Show diff summary when auto-pull imports changes.

Agent detection

detection

Type: object

Default: { auto_enable: false, ignored_agents: [] }

Controls automatic agent detection during sync.

detection:
  auto_enable: false # Auto-enable detected agents without prompting
  ignored_agents: # Agents to never prompt about
    - windsurf
    - aider-md

detection.auto_enable

Type: boolean

Default: false

Auto-enable detected agents without prompting. When true, new agents found in workspace are automatically added to exporters and synced.

Use case: CI/CD environments or when you want all detected agents enabled automatically.

detection.ignored_agents

Type: array of strings

Default: []

Agents to never prompt about during detection. Useful for agents you don’t use even though their files exist in your workspace.

Example:

detection:
  ignored_agents:
    - windsurf # Never prompt about Windsurf
    - aider-md # Never prompt about Aider

Managing ignored agents:

# Add to ignored list
aligntrue adapters ignore windsurf
 
# Manually detect new agents (respects ignored list)
aligntrue adapters detect

Modules and features

modules

Type: object

Default: Mode-specific

Feature flags for optional modules.

modules:
  lockfile: false # Generate .aligntrue.lock.json
  bundle: false # Generate .aligntrue.bundle.yaml
  checks: true # Enable machine-checkable rules
  mcp: false # Enable MCP server

lockfile

Type: object

Default: { mode: "off" } (solo), { mode: "soft" } (team/enterprise)

Lockfile validation mode for reproducible builds.

lockfile:
  mode: soft # off | soft | strict

Values:

• off - No lockfile validation
• soft - Warn on drift but don’t fail
• strict - Fail on any drift (recommended for CI)

Backup and restore

backup

Type: object

Default: { auto_backup: true, keep_count: 5, backup_on: ["sync", "import"] }

Automatic backup configuration.

backup:
  auto_backup: true
  keep_count: 5
  backup_on:
    - sync
    - import

backup.auto_backup

Type: boolean

Default: true

Automatically create backups before destructive operations.

backup.keep_count

Type: number

Default: 5

Number of backups to keep (older backups auto-deleted).

backup.backup_on

Type: array of strings

Values: ["sync", "restore", "import"]

Default: ["sync", "import"]

Which commands trigger auto-backup.

Advanced configuration

scopes

Type: array of objects

Default: undefined

Hierarchical scopes for monorepo path-based rule application.

scopes:
  - path: packages/frontend
    include:
      - "**/*.tsx"
    exclude:
      - "**/*.test.tsx"
    rulesets:
      - typescript.strict
      - react.hooks

merge

Type: object

Default: { strategy: "deep", order: ["root", "path", "local"] }

Merge strategy for multi-source rules.

merge:
  strategy: deep
  order:
    - root
    - path
    - local

performance

Type: object

Default: { max_file_size_mb: 10, max_directory_depth: 10 }

Performance guardrails.

performance:
  max_file_size_mb: 10
  max_directory_depth: 10
  ignore_patterns:
    - node_modules
    - dist

git

Type: object

Default: { mode: "ignore" }

Git integration settings.

git:
  mode: ignore # ignore | commit | branch
  per_adapter:
    cursor: commit
    agents-md: ignore

Example configurations

Minimal (solo mode)

exporters:
  - cursor
  - agents-md

Solo with auto-pull

exporters:
  - cursor
  - agents-md
sync:
  auto_pull: true
  primary_agent: cursor
  workflow_mode: native_format

Team mode

mode: team
exporters:
  - cursor
  - agents-md
modules:
  lockfile: true
  bundle: true
lockfile:
  mode: strict
sync:
  auto_pull: false
  workflow_mode: ir_source

With agent detection

exporters:
  - cursor
  - agents-md
detection:
  auto_enable: false
  ignored_agents:
    - windsurf
    - aider-md
sync:
  auto_pull: true
  primary_agent: cursor

Validation

Config is validated against JSON Schema on load. Common errors:

Invalid mode:

Invalid mode "typo": must be one of solo, team, enterprise

Missing exporters:

At least one exporter must be configured

Invalid sync.workflow_mode:

sync.workflow_mode: must be one of auto, ir_source, native_format

See also

• CLI Reference - Command-line options
• Workflows Guide - Choosing your workflow
• Team Mode - Team-specific config
• Solo Developer Guide - Solo setup