Recommended conventions

Standardized plug keys and overlay patterns help template authors create consistent, interoperable rule Aligns. Users benefit by reusing fills across multiple templates.

Using these conventions is optional but recommended.

Plug key conventions

Plug keys should follow these patterns to maximize interoperability across templates.

Build and test commands

Project metadata

Configuration and file paths

Naming rules

• Use lowercase letters, numbers, dots, hyphens, underscores: ^[a-z0-9._-]+$
• Use dots for namespacing: test.cmd, docs.url, author.name
• Do NOT start with stack. or sys. (reserved for AlignTrue system use)
• Be descriptive: prefer docs.url over just url

Supported plug formats

• command — Single-line shell command; avoid pipes/&&. Prefer a package script (for example, pnpm test) over chained commands.
• text — Single-line UTF-8 text
• file — Repo-relative POSIX path (no .., no absolute paths)
• url — Must start with http:// or https://

Overlay pattern conventions

Overlays customize upstream rules. These patterns are commonly used:

Common severity adjustments

Example severity override:

overlays:
  overrides:
    - selector: "rule[id=no-console-log]"
      set:
        severity: "error"

Selector naming

• Use kebab-case for rule IDs: no-console-log, prefer-const, max-complexity
• Use dot notation for nested properties: check.inputs.threshold, check.inputs.max
• Example selector: rule[id=max-complexity]
• Example override:

  overlays:
    overrides:
      - selector: "rule[id=max-complexity]"
        set:
          "check.inputs.threshold": 15

When to use conventions

Use standard keys when:

• Creating a new template Align
• Adding plugs to an existing Align
• Documenting plugs in your README
• Contributing to community packages

Safe to deviate when:

• Your specific use case has no standard equivalent
• You need a more specific namespace (e.g., backend.test.cmd for backend-specific tests)
• Your project has established internal conventions (document them in your README)

Best practices for rule authors

1. Reference conventions first - Check if a standard key exists before creating a new one
2. Use descriptive names - Be clear about what the plug is for
3. Provide examples - Always include an example value for required plugs
4. Document your plugs - Add a section in your Align’s README explaining custom plugs
5. Test with real fills - Before publishing, set fills and verify output
6. Consider your users - Will they recognize standard keys like test.cmd?

Future: Template library integration

When a community template library is built, conventions will:

• Help users discover compatible templates
• Enable automatic compatibility scoring
• Surface popular patterns to new authors
• Suggest standard keys to prevent duplication

For now, following these conventions in your Aligns creates an immediate benefit: users can reuse the same fills across multiple templates from different authors.

Examples

Simple Align with standard plugs

id: my-testing-align
version: "1"
plugs:
  slots:
    test.cmd:
      description: "Command to run tests"
      format: command
      required: true
      example: "pnpm test"
    docs.url:
      description: "Documentation URL"
      format: url
      required: false

For commands, keep the value to a single, safe invocation (for example, pnpm test). Use a package script for complex pipelines instead of chaining with && or pipes.

User configures once:

aligntrue plugs set test.cmd "pnpm test"
aligntrue plugs set docs.url "https://docs.example.com"

Both fills work across any Align using these standard keys.

Custom namespace for domain-specific plugs

When no standard fits, use a namespace:

backend.db.host:
  description: "Backend database host"
  format: text
  example: "localhost"
 
backend.db.port:
  description: "Backend database port"
  format: text
  example: "5432"

Document these in your README so users understand.

References

• Plugs guide - Complete plugs documentation
• Overlays guide - Complete overlays documentation
• Creating Aligns - How to author Aligns