Configuration reference

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

Overview

AlignTrue uses YAML configuration files in the .aligntrue/ directory.

Format: YAML (validated against JSON Schema on load)

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

Solo mode (single file)

In solo mode, all configuration is in one file:

• config.yaml - All settings (committed to git)

Team mode (two files)

In team mode, configuration is split into two files:

Why two files?

• Personal settings (like remotes.personal) don’t cause merge conflicts
• Local overrides (like git.mode) don’t affect team behavior
• Team settings are reviewed via PR
• Easy to toggle team mode on/off without losing settings

Field ownership:

Merging behavior:

• Arrays (sources, exporters): Team + personal combined
• Scalars (git.mode, etc.): Personal overrides team locally
• Lockfile: Generated from team config only

Team enable defaults:

• sources are moved into config.team.yaml (team-owned inputs).
• exporters stay in personal config.yaml by default; team can add a shared baseline if desired. Final exporters are the union of team + personal.

remotes (routing in team mode)

Type: object

Controls where rules are pushed. Remotes push during aligntrue sync by default unless you set auto: false on a remote; use aligntrue remotes push for explicit/manual pushes.

Rules have a single scope (team, personal, or shared). To send a rule to multiple remotes, keep one scope and add remotes.custom[] entries with include patterns. Solo mode routes all rules to remotes.personal (unless scope: shared and a shared remote exists); team/enterprise use scope-based routing. For routing details, see Rule sharing & privacy.

Core fields

mode

Type: string

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

Default: "solo"

Location: config.team.yaml in team mode, config.yaml in solo mode

Operating mode that determines default behavior for lockfiles and bundles.

# Solo mode (config.yaml)
mode: solo
 
# Team mode (config.team.yaml)
mode: team

In team mode, mode is determined by the presence of config.team.yaml, not by a field in config.yaml.

exporters

Type: array of strings

Default: ["cursor", "agents"] (auto-filled if omitted)

Required: Yes (at least one)

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

exporters:
  - cursor
  - agents
  - vscode-mcp

See Agent Support for all 50 available exporters.

Team mode behavior: Exporters are shared/merged, but enabling team mode does not move personal exporters into config.team.yaml. Add exporters to the team file only when the team wants a standard baseline; personal config can still add more.

sources

Type: array of objects

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

Where to load rules from. Supports local files and git repositories.

GitHub sources are resolved as .align.yaml packs first (repo root, subdirectory, or direct manifest). If no manifest is found, import falls back to recursive .md/.mdc scanning. See Align packs for manifest fields and limits.

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

Sync behavior

sync

Type: object

Controls sync behavior and optional features.

sync:
  source_order: [] # Optional rule order by basename
  source_markers: auto # auto | always | never
  content_mode: auto # auto | inline | links
  auto_manage_ignore_files: prompt # prompt | true | false (defaults effectively to true)
  cleanup: all # all | managed

sync.source_order

Custom ordering of rule files by basename. When unset, rules are processed alphabetically.

sync.source_markers

auto (default) shows source markers only when multiple sources are merged; always forces markers; never omits them.

sync.content_mode

auto (default) inlines a single rule and uses links when there are multiple; inline always embeds; links always links.

sync.auto_manage_ignore_files

prompt asks interactively before writing ignore files; true always writes; false never writes. If unset, CLI behavior defaults to true (no prompt).

sync.cleanup

all (default) removes all files matching agent patterns when formats change; managed removes only files previously created by AlignTrue.

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

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 # Never prompt about Aider

Managing ignored agents:

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

Modules and features

modules

Type: object

Default: Mode-specific

Feature flags for optional modules.

• Solo: lockfile false, checks true, mcp false
• Team: lockfile true, checks true, mcp false
• Enterprise: lockfile true, checks true, mcp true

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

lockfile (deprecated)

Note: The lockfile.mode setting has been removed. Lockfile is now enabled via modules.lockfile: true in team mode.

Drift enforcement happens in CI using aligntrue drift --gates.

# Old (deprecated):
# lockfile:
#   mode: soft
 
# New approach:
modules:
  lockfile: true # Enable lockfile generation
 
# CI enforcement:
# aligntrue drift --gates  # Fails CI if drift detected

Lockfile v2 stores version and bundle_hash (team rules + config.team.yaml). Use aligntrue drift to check for drift.

Backup and restore

backup

Type: object

Default: { retention_days: 30, minimum_keep: 3 }

Automatic backup configuration for age-based retention.

backup:
  retention_days: 30 # How many days to keep backups
  minimum_keep: 3 # Always keep at least this many recent

backup.retention_days

Type: number

Default: 30

Age-based retention in days. Backups older than this are automatically deleted after sync.

• 0 - Never auto-delete (manual cleanup only)
• 30 - Default: delete backups older than 30 days
• 365 - Keep backups for one year

backup.minimum_keep

Type: number

Default: 3

Safety floor: always keep at least this many of the most recent backups, regardless of age.

• Minimum: 1
• Typical: 3-5
• Protects against over-cleanup when syncing infrequently

backup.keep_count (removed)

Type: number (deprecated and removed)

Count-based retention. No longer used if retention_days is present. Kept for backward compatibility with existing configs.

managed

Type: object

Default: undefined

Team mode only.

Controls which sections are protected as managed content and how they are documented in agent exports.

managed:
  files:
    - AGENTS.md
  sections:
    - "Security Standards"
    - "Code Review Checklist"
  source_url: "https://github.com/company/rules"

managed.files

List of full file paths to protect from direct edits (e.g., AGENTS.md).

managed.sections

Type: array of strings

List of section headings that are treated as team-managed. Each managed section is marked with [TEAM-MANAGED] warnings in exported files and cannot be edited directly without removing it from this list.

managed.source_url

Type: string

Optional

URL to the canonical repository or documentation for team-managed sections. Displayed to developers so they can find the source of truth.

See also: Team guide

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

Defaults:

• mode: ignore (solo/team), commit (enterprise)
• branch_check_interval: 86400 seconds
• tag_check_interval: 604800 seconds
• offline_fallback: true
• auto_gitignore: auto

Git integration settings.

git:
  mode: ignore # ignore | commit | branch
  per_exporter:
    cursor: commit
    agents: ignore
  branch_check_interval: 86400
  tag_check_interval: 604800
  offline_fallback: true
  auto_gitignore: auto # auto | always | never

Behavior:

• Applies to generated agent exports (.cursor/rules, AGENTS.md, etc.). Solo/team default to ignore to avoid PR noise; enterprise defaults to commit for auditability.
• Agents still work when exports are gitignored as long as aligntrue sync runs (locally or in CI).
• Use per_exporter overrides when a specific export must be tracked (e.g., commit AGENTS.md, ignore .cursor/rules/).
• Rules with gitignore: true in frontmatter create a dedicated managed block in .gitignore that lists only their exported files (e.g., .cursor/rules/guardrails.mdc), regardless of git.mode. Use this for selective non-commit of sensitive rules while keeping other exports tracked.

export

Type: object

Controls mode hints in non-Cursor formats and token limits.

export:
  mode_hints:
    default: metadata_only # off | metadata_only | hints | native
    overrides:
      agents: off
  max_hint_blocks: 20
  max_hint_tokens: 1600

remotes

Type: object

Configure pushing .aligntrue/rules/ to git repositories by scope and pattern.

remotes:
  personal: git@github.com:user/personal-rules.git
  shared:
    url: git@github.com:org/shared-rules.git
    branch: main
    # Optional: set auto: false to require manual push
  custom:
    - id: security
      url: git@github.com:org/security-rules.git
      include:
        - security/**

overlays

Type: object

Declarative modifications to upstream rules. Conflicts fail by default.

overlays:
  overrides:
    - selector: "rule[id=authn]"
      set:
        severity: MUST
# allow conflicts (last-writer-wins)
allow_overlay_conflicts: false

Notes:

• Supported selectors: rule[id=...], sections[index] (property/heading selectors are deprecated)
• Use set: { key: null } to remove properties (remove is deprecated)
• To allow conflicts instead of failing, set allow_overlay_conflicts: true or pass --allow-overlay-conflicts

plugs

Type: object

Template slot fills for rules. Fills are config-only; sync fails if required plugs are missing.

plugs:
  fills:
    service_name: checkout
    test.cmd: "pnpm test" # required plugs must be set

Notes:

• Supported formats: command, text (file/url are deprecated and treated as text)

approval

Type: object

Approval workflow for team mode.

approval:
  internal: pr_approval
  external: pr_approval

mcp

Type: object

Model Context Protocol server definitions.

mcp:
  servers:
    - name: aligntrue
      command: npx
      args:
        - "@aligntrue/mcp-server"
      env:
        NODE_ENV: production
      disabled: false

Example configurations

Minimal (solo mode)

exporters:
  - cursor
  - agents

Team mode

mode: team
exporters:
  - cursor
  - agents
modules:
  lockfile: true
  bundle: true
lockfile:
  mode: strict

With agent detection

exporters:
  - cursor
  - agents
detection:
  auto_enable: false
  ignored_agents:
    - windsurf
    - aider

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

See also

• CLI Reference - Command-line options
• Sync behavior - Understanding sync flow
• Team Mode - Team-specific config
• Solo Developer Guide - Solo setup