Customization technical reference

This page provides technical implementation details for working with plugs, overlays, and scopes. For user-facing guides, see Plugs, Overlays, and Scopes.

Where to Declare Features

Plugs slots:

• Declared in pack files (markdown with fenced blocks or .aligntrue/.rules.yaml IR)
• Example: examples/packs/testing.md with fenced block

Plugs fills:

• Declared in .aligntrue/config.yaml (project-level fills)
• OR in pack files as stack-level defaults

Overlays:

• Declared in .aligntrue/config.yaml only (under overlays.overrides:)
• Applied at sync time before export

Scopes:

• Declared in .aligntrue/config.yaml only (under scopes:)
• Applied at load time before plugs/overlays

Authoring Formats

AlignTrue supports two authoring formats:

Markdown with Fenced Blocks (Recommended for Packs)

# Testing Pack
 
Use consistent test commands across your project.
 
```aligntrue
id: testing-pack
version: 1.0.0
 
plugs:
  slots:
    test.cmd:
      description: "Command to run tests"
      format: command
      required: true
      example: "pytest -q"
 
rules:
  - id: testing.run-tests
    severity: error
    guidance: |
      Run tests before committing: [[plug:test.cmd]]
```

Direct YAML (Internal IR Format)

# .aligntrue/.rules.yaml (generated/maintained by system)
id: testing-pack
version: 1.0.0
plugs:
  slots:
    test.cmd:
      description: "Command to run tests"
      format: command
rules:
  - id: testing.run-tests
    severity: error
    guidance: "Run tests: [[plug:test.cmd]]"

Data Flow

Pack files (.md) → System parses → Internal IR (.rules.yaml) → Exporters → Agent formats (AGENTS.md, .mdc)

Note: AGENTS.md is an export target, not a primary authoring surface. Edit pack files or .aligntrue/config.yaml instead.

Plugs Resolution Algorithm

1. Normalize CRLF/CR to LF in rule text
2. Protect escapes: sentinel-replace [[\plug: temporarily
3. For each [[plug:<key>]]:
   • If fill exists → replace with fill value
   • If required and no fill → insert TODO block
   • If optional and no fill → replace with empty string
4. Unescape sentinel back to [[plug: for [[\plug:...]
5. Ensure single trailing LF

TODO Block Format (Exact Bytes, LF Only)

With example:

TODO(plug:<key>): Provide a value for this plug.
Examples: <example-from-slot>

Without example:

TODO(plug:<key>): Provide a value for this plug.

Merge Order

Base < stack pack(s) < repo. Last writer wins.

Plugs Format Types

• command - Single-line command, no env vars except CI=true
• text - Any single-line UTF-8 string
• file - Repo-relative POSIX path, no .. segments, no absolute paths
• url - Must start with http:// or https://

Plugs Key Naming Rules

• Pattern: ^[a-z0-9._-]+$
• Cannot start with stack. or sys. (reserved)
• Use dots for namespacing: test.cmd, docs.url, author.name

Overlays Selector Syntax

• By rule ID: rule[id=no-console-log]
• By property path: profile.version
• By array index: rules[0] (less common, prefer ID)

Overlays Operations

Set Operation (Supports Dot Notation)

overlays:
  overrides:
    - selector: "rule[id=no-console-log]"
      set:
        severity: "error" # Simple property
        "check.inputs.maxLength": 120 # Nested property
        autofix: false # Disable autofix

Remove Operation

overlays:
  overrides:
    - selector: "rule[id=max-complexity]"
      remove:
        - "autofix"
        - "tags"

Combined

overlays:
  overrides:
    - selector: "rule[id=line-length]"
      set:
        severity: "warning"
        "check.inputs.threshold": 120
      remove:
        - "autofix"

Severity Values

"off", "info", "warning", "error"

Application Order

Overlays apply in definition order. Last matching overlay wins if multiple target same rule.

Scopes Path Rules

• Must be relative (no leading /)
• No parent directory traversal (.. not allowed)
• Use forward slashes (POSIX-style)
• Use . for workspace root

Scopes Include/Exclude

• Standard glob syntax (micromatch)
• Relative to scope path
• Multiple patterns allowed
• Exclude applied after include

Scopes Merge Order (Default)

merge:
  strategy: "deep"
  order: ["root", "path", "local"]

1. root - Rules from workspace root config
2. path - Rules from scope-specific configs
3. local - Rules from nested/local configs

Last writer wins for conflicts.

Integration and Order

When using multiple customization features together, they apply in this order:

1. Scopes - Filter rules by path
2. Plugs - Resolve template slots
3. Overlays - Apply property overrides

Determinism and Hashing

Plugs

• Lock hash - Computed over canonicalized YAML pre-resolution
• Export hash - Computed over fully resolved text post-resolution
• Fills are not volatile - they affect export hash

Overlays

• base_hash - Upstream content
• overlay_hash - Local modifications
• result_hash - Combined result
• Tracked in lockfile for drift detection

Scopes

• Applied at load time before plugs and overlays
• Merge order is deterministic
• Path validation prevents security issues

Validation Rules

Plugs

• Every [[plug:...]] must have declared slot
• Fills must be non-empty, single-line scalars
• Keys cannot start with stack. or sys.
• Format validation (command, text, file, url)
• Required slots must have fills or render TODO blocks

Overlays

• Selectors must match existing rules
• Severity values must be valid (off, info, warning, error)
• Property paths use dot notation for nested properties
• Remove operations list property names to delete
• Stale selectors (no match) flagged in override status

Scopes

• Paths must be relative (no leading /)
• No parent directory traversal (..)
• Glob patterns must be syntactically valid
• Merge order values must be root, path, or local
• No duplicate values in merge order
• Rulesets must reference existing rule pack IDs

Best Practices

For Plugs

1. Provide examples for required slots
2. Use most restrictive format (command > file > text)
3. Mark as optional unless truly required
4. Namespace keys with dots: test.cmd, docs.url
5. Never put secrets in fills (use env vars at runtime)

For Overlays

1. Keep overlays minimal (fewer = easier updates)
2. Document reasons with YAML comments
3. Track expiration dates for temporary overrides
4. Review regularly with override status
5. Consolidate duplicate overlays

For Scopes

1. Start simple, add complexity only when needed
2. Use shared base rules across all scopes
3. Map scopes to team ownership boundaries
4. Exclude test files if rules differ
5. Document scope ownership with comments

CLI Workflows

Plugs Workflow

# 1. Audit slots and fills
aligntrue plugs audit
 
# 2. Set required fills
aligntrue plugs set test.cmd "pnpm test"
 
# 3. Preview resolution
aligntrue plugs resolve
 
# 4. Sync to agents
aligntrue sync

Overlays Workflow

# 1. Add overlay
aligntrue override add \
  --selector 'rule[id=no-console-log]' \
  --set severity=error
 
# 2. View all overlays
aligntrue override status
 
# 3. Show effects
aligntrue override diff
 
# 4. Sync to agents
aligntrue sync

Scopes Workflow

# 1. Configure scopes in .aligntrue/config.yaml
aligntrue scopes
 
# 2. Validate
aligntrue check
 
# 3. Sync to agents
aligntrue sync

Related Documentation

• Plugs Guide
• Overlays Guide
• Scopes Guide
• CLI Reference
• Solo Developer Guide
• Team Guide