Skip to Content
03 ConceptsGlossary

Glossary

Essential terms and concepts used throughout AlignTrue documentation and CLI.

Core Concepts

Agents

AI coding assistants that AlignTrue exports rules to. Examples include:

  • Cursor (.mdc files)
  • GitHub Copilot (AGENTS.md format)
  • Claude Code (AGENTS.md + Claude-specific formats)
  • Aider, Windsurf, VS Code MCP, and 24+ others

AlignTrue supports 28+ agents through 43 specialized exporters, each optimized for that agent’s native format.

Related: Agent Support

Rules

Individual guidelines that specify how AI agents should behave in your project. Each rule includes:

  • ID - Unique identifier (e.g., require-tests, no-any-type)
  • Severity - error, warn, or info
  • Applies to - Glob patterns for which files the rule applies to
  • Guidance - Human-readable explanation for AI agents
  • Optional: Checks, autofixes, and vendor-specific metadata

Example: “All TypeScript files must have strict mode enabled”

Related: Align Spec, Markdown authoring

Packs

Collections of related rules organized around a theme or technology stack. Packs are the shareable unit of rule sets.

Examples of packs:

  • testing.yaml - Testing best practices
  • typescript.yaml - TypeScript strict mode conventions
  • nextjs_app_router.yaml - Next.js App Router patterns

Packs can be:

  • Stored locally
  • Shared via GitHub
  • Referenced in your AlignTrue configuration

Related: Creating Packs

Aligns

The complete YAML document format that combines metadata with a collection of rules. An Align defines:

  • ID - Unique identifier for the pack or rules
  • Version - Semantic versioning (e.g., 1.0.0)
  • Summary - Brief description
  • Rules - Array of rule objects
  • Optional metadata - Owner, source, tags, scope, etc.

“Aligns” is the formal name for the complete specification format, used in the Align Spec v1 documentation.

Related: Align Spec v1 

File Types & Formats

AGENTS.md

The primary user-editable file where you write and maintain rules in markdown format. Contains:

  • Human-readable rule descriptions
  • Fenced ```aligntrue code blocks with YAML rule definitions
  • Optional narrative sections explaining your project’s standards

AGENTS.md serves as the bridge between human-readable documentation and machine-parseable rules.

Related: Markdown authoring

Intermediate Representation (IR)

The internal YAML format that AlignTrue uses internally. Stored in .aligntrue/.rules.yaml.

Key characteristics:

  • Auto-generated from AGENTS.md or imported from agent files
  • Machine-parseable, pure YAML (no markdown)
  • Canonical source for rule validation and export
  • Not intended for direct editing

The IR sits between user-editable files and exported agent formats:

AGENTS.md (user-editable) → IR (.rules.yaml) → Agent exports (.mdc, MCP configs, etc.)

Cursor Rules (.mdc)

Cursor’s native rule format stored in .cursor/rules/*.mdc. Files use Markdown with fenced YAML blocks optimized for Cursor’s inline rule engine.

AlignTrue automatically exports your rules to .mdc format when you run aligntrue sync.

Related: Cursor documentation 

MCP Configuration

Model Context Protocol configuration stored in .vscode/mcp.json for VS Code and other MCP-compatible agents. Allows agents to access external tools and resources.

AlignTrue exports MCP server configurations automatically for compatible agents.

Related: Model Context Protocol 

Operations

Sync

The process of converting and pushing your rules to all configured agent formats. Ensures all agents stay aligned with your current rule set.

Command: aligntrue sync

What happens:

  1. Loads your rules from AGENTS.md or .aligntrue/.rules.yaml
  2. Validates them against the Align Spec
  3. Exports to all configured agent formats (.mdc, AGENTS.md, MCP configs, etc.)
  4. Writes updated files to disk

Related: Sync behavior

Export

Converting rules from the IR (Intermediate Representation) into a specific agent’s native format. AlignTrue uses 43 specialized exporters to handle 28+ different agent formats.

Each exporter:

  • Preserves rule semantics where possible
  • Adapts formatting to agent requirements
  • Adds fidelity notes when parity isn’t exact

Auto-pull

In solo mode, automatically imports any changes you made directly in agent files (e.g., .cursor/rules/*.mdc) back into AGENTS.md before syncing.

Behavior:

  • Enabled by default in solo mode
  • Disabled in team mode (to prevent accidental overwrites)
  • Can be disabled with aligntrue sync --no-auto-pull

This enables two-way sync: edit either AGENTS.md or agent files, and changes propagate to both.

Related: Sync behavior

Bundle

Merging rules from multiple packs/sources into a single coherent rule set (team mode only).

When bundling happens:

  • Specified in .aligntrue/config.yaml under sources
  • Multiple packs are resolved with precedence rules
  • Dependencies are resolved recursively
  • Final bundle is deterministically merged

Related: Team mode

Lockfile

A deterministic snapshot of your complete rule set with cryptographic hashes (team mode only). File: .aligntrue.lock.json

Purpose:

  • Ensures reproducible deployments across machines
  • Enables drift detection (detects when rules diverge)
  • Pins exact versions for team collaboration
  • Includes canonical SHA-256 hashes for integrity verification

Lockfiles are generated via aligntrue sync or aligntrue lock in team mode.

Related: Team mode, Drift detection

Drift Detection

Comparing your current rule state against a committed lockfile to detect when rules have changed (team mode only).

Drift scenarios:

  • A pack was updated but lockfile wasn’t regenerated
  • Someone manually edited .aligntrue/.rules.yaml
  • A rule source is no longer accessible
  • A team member pushed different rules than the lockfile

Command: aligntrue check --drift (in team mode)

Related: Drift detection

Configuration & Modes

Solo Mode

Default mode for individual developers. Optimized for fast iteration with minimal ceremony.

Characteristics:

  • No lockfile required
  • No bundle overhead
  • Simple rule management
  • Auto-pull enabled by default
  • Fast sync operations

Use case: Single developer, single project, local rules only

Related: Solo developer guide

Team Mode

Collaborative mode with reproducibility guarantees and approval workflows.

Characteristics:

  • Lockfile generation for determinism
  • Bundle support for multi-source rules
  • Allow list validation for approved sources
  • Drift detection enabled
  • Auto-pull disabled by default

Enable with: aligntrue team enable

Related: Team mode, Team guide

Allow List

In team mode, a list of approved sources (git repos, URLs) from which rules can be pulled. Prevents unauthorized rule additions and ensures security.

File: .aligntrue.allow

Use: Ensures only vetted, team-approved rule sources are used

Related: Team mode

Configuration File

Main AlignTrue configuration stored in .aligntrue/config.yaml. Defines:

  • Mode - solo or team
  • Sources - Where rules come from (local, git, catalog)
  • Exporters - Which agent formats to export to
  • Scopes - Path-based rule application (monorepos)
  • Modules - Feature toggles (lockfile, bundle, auto-pull)

Related: Config reference

Advanced Features

Vendor Bags

Optional agent-specific metadata stored under vendor.<agent-name> that preserves information during round-trip conversions.

Purpose:

  • Store agent-specific hints that don’t map to standard rule fields
  • Enable lossless IR ↔ agent conversions
  • Prevent loss of fidelity when syncing to different formats

Example:

vendor:
  cursor:
    ai_hint: "Suggest test scaffolding with vitest"
    session_id: "xyz"
  _meta:
    volatile: ["cursor.session_id"] # Excluded from hashing

Related: Vendor bags

Overlays

Customizations applied on top of third-party packs without forking them. Allows safe, maintainable modifications to upstream rule sets.

Features:

  • Override specific rules
  • Add new rules
  • Change severity levels
  • Maintain sync with upstream versions

Related: Overlays

Scopes

Path-based rule application for monorepos. Allows different rules to apply to different directories or projects within a single repository.

Use cases:

  • Backend rules for packages/api/
  • Frontend rules for apps/web/
  • Shared infrastructure rules for root level

Related: Scopes

Plugs

Parameterized rule templates that accept configuration inputs. (Phase 2.5 feature)

Purpose:

  • Create reusable rule templates
  • Accept configuration via fills in overlays
  • Support community-contributed rule templates

Related: Plugs

Last updated on
Git workflows guideSync behavior