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 33 agents through 51 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, Natural Markdown Sections

Align (noun)

An Align is the shareable unit in AlignTrue. It replaces the earlier concept of a “pack” from prior terminology.

An Align can be:

• A collection of rules (e.g., typescript.md, testing.md)
• An MCP server configuration
• A skill definition
• Other shareable elements (as needed)

Key points:

• Capitalize Align (singular) and Aligns (plural) as proper nouns when referring to the shareable unit
• Distinguish from the verb “align” (lowercase) meaning to synchronize or keep in sync
• Can be stored locally, shared via git, or referenced remotely
• Combines metadata (ID, version, summary) with rules or other configuration

Examples of Aligns:

• “The TypeScript Align includes strict mode rules”
• “Import community Aligns from GitHub”
• “Create your own Align for project standards”
• testing.md - Testing best practices Align
• nextjs_app_router.md - Next.js App Router patterns Align

File formats: .md files in .aligntrue/rules/

Related: Align Spec v1 , Creating Aligns

File types & formats

Align source files (.aligntrue/rules/*.md)

Primary authoring files that you edit. AlignTrue compiles these markdown Aligns into its internal IR and writes agent-specific exports from them. Treat all generated exports as read-only—update .aligntrue/rules/*.md and rerun aligntrue sync to propagate changes.

AGENTS.md

The universal markdown export AlignTrue writes for agents that consume a shared format. Contains:

• Human-readable rule descriptions
• Natural markdown sections with YAML frontmatter
• Optional narrative sections explaining your project’s standards

AGENTS.md is generated by aligntrue sync for compatible agents. Edit .aligntrue/rules/*.md instead of modifying this export directly.

Related: Natural Markdown Sections

Intermediate representation (IR)

The internal YAML format AlignTrue builds in memory from .aligntrue/rules/*.md.

Key characteristics:

• Normalizes Aligns for validation and exporters
• Machine-parseable, pure YAML (no markdown)
• Used internally for validation and export
• Not stored on disk—rerun aligntrue sync after editing .aligntrue/rules/*.md

The IR sits between your authoring files and exported agent formats:

.aligntrue/rules/*.md (you edit) → IR (in memory) → Agent exports (.mdc, AGENTS.md, MCP configs, etc.)

Cursor rules (.mdc)

Cursor’s native rule format stored in .cursor/rules/*.mdc. Files use YAML frontmatter with markdown content optimized for Cursor’s inline rule engine.

AlignTrue automatically exports your rules to .mdc format when you run aligntrue sync. Do not edit .cursor/rules/*.mdc directly; update .aligntrue/rules/*.md instead.

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 .aligntrue/rules (and any configured sources)
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 50 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

Bundle

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

When bundling happens:

• Specified in .aligntrue/config.yaml under sources
• Multiple Aligns 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 when team mode is enabled. Solo mode does not write a lockfile.

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:

• An Align was updated but the lockfile wasn’t regenerated
• Rules changed in .aligntrue/rules without rerunning aligntrue sync
• A rule source is no longer accessible
• A team member pushed different rules than the lockfile

Command: aligntrue 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
• 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
• Drift detection enabled

Enable with: aligntrue team enable

Related: Team mode, Team guide

Configuration file

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

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

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 Aligns 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. (Plugs system)

Purpose:

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

Related: Plugs

Related documentation

• Getting started: Quickstart guide
• Concepts: Sync behavior, Team mode, Drift detection
• How-to guides: Solo developer guide, Team guide
• Reference: CLI reference, Config reference, Agent support