Customization overview

AlignTrue provides three complementary mechanisms for customizing rules to fit your project, stack, and team needs without forking upstream Aligns. Author rules in .aligntrue/rules/*.md; agent exports like AGENTS.md and .cursor/rules/*.mdc are generated outputs—treat them as read-only.

The three pillars

If you’re unsure where to start: use plugs for project-specific values, overlays for behavior changes, and scopes for monorepo or path-based splits.

Plugs - Fill template slots

What: Dynamic configuration slots that get filled with stack-specific or project-specific values.

When to use:

• Test commands that vary by stack (pytest vs pnpm test)
• File paths specific to your project structure
• URLs, author names, or other project metadata
• Any value that differs between projects using the same rules

Example:

# Rule with plug
guidance: |
  Run tests with: [[plug:test.cmd]]
 
plugs:
  slots:
    test.cmd:
      description: "Command to run tests"
      format: command
      required: true
      example: "pytest -q"
  fills:
    test.cmd: "pnpm test" # Your project's value

Learn more about plugs →

Overlays - Override rule properties

What: Declarative overrides that modify upstream rule properties without forking.

When to use:

• Adjust severity levels (warning → error, or disable entirely)
• Add check inputs for project-specific thresholds
• Remove autofix while keeping the check
• Temporary adjustments during migration periods

Example:

overlays:
  overrides:
    - selector: "rule[id=no-console-log]"
      set:
        severity: "error" # Upgrade from warning to error

Learn more about overlays →

Scopes - Apply rules by path

What: Path-based rule application for monorepos with different requirements per directory.

When to use:

• Monorepos with frontend + backend + services
• Different tech stacks in different directories
• Team boundaries within a monorepo
• Progressive rule adoption (strict in new code, lenient in legacy)

Example:

scopes:
  - path: "apps/web"
    include: ["**/*.ts", "**/*.tsx"]
    rulesets: ["nextjs-rules", "react-rules"]
 
  - path: "packages/api"
    include: ["**/*.ts"]
    rulesets: ["node-rules", "api-rules"]

Learn more about scopes →

Decision tree

Use this flowchart to choose the right customization mechanism:

Feature comparison

Solo vs team patterns

Solo developer patterns

Plugs:

• Set repo-local fills for your project (aligntrue plugs set test.cmd "pnpm test")
• Override stack align defaults with your preferences
• Quick iteration without committing to team standards

Overlays:

• Temporarily disable strict rules during refactoring
• Adjust severity for personal workflow
• Experiment with rule configurations

Scopes:

• Organize personal monorepo with different rules per app
• Progressive adoption (strict in new code, lenient in old)
• Stack-specific rules (Next.js vs Node.js vs Python)

Team patterns

Plugs:

• Stack Aligns provide default fills
• Teams override with org-specific values
• Shared fills committed to repo for consistency

Overlays:

• Team-wide severity preferences
• Adjust third-party Aligns to team standards
• Document customization decisions in config

Scopes:

• Team boundaries in monorepo (team A owns apps/web, team B owns packages/api)
• Shared base rules + scope-specific overrides
• Gradual rollout (strict in new modules, lenient in legacy)

Integration and order

When using multiple customization features together, this is the actual pipeline AlignTrue runs:

1. Scopes - Filter rules by path at load time
2. Plugs - Resolve template slots before export
3. Overlays - Apply property overrides before export

Example workflow:

# 1. Scopes: Apply different rules to web vs api
scopes:
  - path: "apps/web"
    rulesets: ["nextjs-rules"]
  - path: "packages/api"
    rulesets: ["node-rules"]
 
# 2. Plugs: Fill stack-specific values
plugs:
  fills:
    test.cmd: "pnpm test"
    docs.url: "https://docs.example.com"
 
# 3. Overlays: Adjust severity for team
overlays:
  overrides:
    - selector: "rule[id=no-console-log]"
      set:
        severity: "error"

Find your scenario

Looking for a specific use case? Browse our comprehensive scenario examples organized by feature:

By problem type

Monorepo & Organization:

• Progressive adoption - Different rules for new vs legacy code
• Team boundaries - Different teams own different directories
• Multi-stack monorepo - Multiple languages/tech stacks
• Frontend-backend split - Separate concerns
• Microservices - Service-specific rules

Customization:

• Test command - Different test runners per project
• Organization metadata - Company-specific values
• Stack-specific paths - Config file locations per stack

Rule Modification:

• Severity upgrade - Make warnings errors
• Temporary migration - Disable strict rules during refactor
• Threshold adjustment - Project-specific complexity limits
• Autofix removal - Keep check but disable risky autofix
• Gradual rollout - Progressive rule adoption

By keyword

Search the docs for keywords like:

• “monorepo”, “team boundaries”, “progressive adoption”
• “test command”, “organization metadata”, “stack-specific”
• “severity”, “migration”, “threshold”, “autofix”, “rollout”

Each scenario includes:

• Problem description
• Complete configuration
• Expected outcomes
• Keywords for search

Common scenarios

Scenario 1: Solo dev with Next.js + Node.js monorepo

Goal: Different rules for frontend and backend, custom test commands

Solution:

• Scopes for frontend vs backend
• Plugs for test commands
• Overlays to adjust severity during migration

scopes:
  - path: "apps/web"
    rulesets: ["nextjs-rules"]
  - path: "packages/api"
    rulesets: ["node-rules"]
 
plugs:
  fills:
    test.cmd: "pnpm test"
 
overlays:
  overrides:
    - selector: "rule[id=strict-null-checks]"
      set:
        severity: "warn" # Temporarily downgrade during migration

Scenario 2: Team sharing TypeScript standards

Goal: Consistent TypeScript rules across team, team-specific severity preferences

Solution:

• Pull upstream TypeScript align
• Overlays for team severity preferences
• Plugs for org-specific values

sources:
  - git: https://github.com/org/typescript-standards
    ref: v1.0.0
 
plugs:
  fills:
    org.name: "Acme Corp"
    test.cmd: "pnpm test"
 
overlays:
  overrides:
    - selector: "rule[id=no-any]"
      set:
        severity: "error" # Team treats this as error

Scenario 3: Monorepo with multiple teams

Goal: Shared base rules, team-specific overrides, different stacks per team

Solution:

• Scopes for team boundaries
• Shared base Align + team-specific Aligns
• Overlays for team preferences

scopes:
  - path: "apps/web"
    rulesets: ["base-rules", "nextjs-rules"]
  - path: "apps/mobile"
    rulesets: ["base-rules", "react-native-rules"]
  - path: "services/api"
    rulesets: ["base-rules", "node-rules"]
 
overlays:
  overrides:
    # Team A: Strict on web
    - selector: "rule[id=accessibility]"
      set:
        severity: "error"

Next steps

• Plugs guide - Fill template slots with project-specific values
• Overlays guide - Override rule properties without forking
• Scopes guide - Apply different rules per directory
• Rule organization - Organize rules across files
• Export formats - Choose native or AGENTS.md format
• Per-rule targeting - Control which agents receive rules
• Solo developer guide - Complete solo workflow
• Team guide - Team collaboration patterns

CLI commands

• aligntrue plugs list - List slots and fills
• aligntrue plugs validate - Check for undeclared/missing/invalid fills
• aligntrue plugs set <key> <value> - Set fill value
• aligntrue override add - Create overlay
• aligntrue override status - View overlays
• aligntrue scopes - List configured scopes

See CLI Reference for complete command documentation.