Skip to Content
Getting startedNext steps

Next steps

You’ve got AlignTrue set up and syncing. Here’s what to explore next based on your needs.

Edit rules in .aligntrue/rules/*.md. aligntrue sync writes exports (like AGENTS.md and .cursor/rules/*.mdc)—treat those as read-only.

Essential commands

These commands will be part of your daily workflow:

Preview changes

See what would change without writing files:

aligntrue sync --dry-run

Validate rules

Check rules for errors (great for CI):

aligntrue check

Check syntax

Lint your markdown rules file:

aligntrue md lint

Full command reference: CLI Reference

Auto-sync on save

Want rules to sync automatically when you save? Set up a file watcher on .aligntrue/rules (and config if needed).

VS Code (quick option)

Add to .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "AlignTrue Auto-Sync",
      "type": "shell",
      "command": "aligntrue sync",
      "runOptions": {
        "runOn": "folderOpen"
      }
    }
  ]
}

Universal option (any editor)

Use nodemon to watch for changes:

Install nodemon:

bash npm install -g nodemon

Run nodemon:

nodemon --watch .aligntrue/rules --watch .aligntrue/config.yaml --exec "aligntrue sync"

Learn more: CLI reference

Using git sources

Pull rules from any git repository to share across projects or teams.

Recommended: Add as a connected source to keep it updated on sync:

aligntrue add source https://github.com/yourorg/rules
aligntrue sync

The add source subcommand automatically adds the source to your .aligntrue/config.yaml and fetches updates on each sync. First sync will prompt for privacy consent.

Alternative: Manually edit .aligntrue/config.yaml if you prefer:

sources:
  - type: git
    url: https://github.com/yourorg/rules
    ref: main
    path: . # Scans directory for .md/.mdc files

Full documentation: Git Sources Guide

Team collaboration

Enable team mode for shared rules with lockfiles and drift detection.

For repository owners

# 1. Enable team mode
aligntrue team enable
 
# 2. Approve rule sources
 
# 3. Sync to generate lockfile
aligntrue sync
 
# 4. Commit team files
git add .aligntrue/
git commit -m "Enable AlignTrue team mode"

For team members

# Clone and sync
git clone <repo> && cd <repo>
aligntrue sync

Team mode provides:

  • Lockfile generation for reproducibility
  • Drift detection (aligntrue drift --gates for CI)
  • Git-based approval workflows
  • Reproducible builds

Complete workflows: Team Mode Guide

Supporting more agents

AlignTrue supports 28+ AI coding agents out of the box.

List available exporters

aligntrue exporters list

Enable additional agents

Recommended: Use the exporters command to enable agents interactively:

aligntrue exporters list          # See all available agents
aligntrue exporters enable --interactive  # Choose which ones to enable

Or enable specific agents directly:

aligntrue exporters enable windsurf claude cline

Alternative: Manually edit .aligntrue/config.yaml:

exporters:
  - cursor
  - agents
  - windsurf
  - claude
  - cline
  - copilot
  - aider

Common agent formats:

  • cursor - Cursor .mdc files
  • agents - Universal AGENTS.md format (works with Copilot, Claude Code, Aider)
  • windsurf - Windsurf rules format
  • cline - Cline configuration
  • vscode-mcp - VS Code MCP configuration

Customization features

AlignTrue provides three powerful mechanisms for customizing rules without forking:

Plugs

Fill template slots with stack-specific values:

aligntrue plugs set test.cmd "pnpm test"

Overlays

Customize third-party Aligns without losing upstream updates:

aligntrue override add --selector 'rule[id=no-console-log]' --set severity=error

Scopes

Apply different rules to different directories:

scopes:
  - path: "apps/web"
    rulesets: ["base-rules", "nextjs-rules"]
  - path: "packages/api"
    rulesets: ["base-rules", "node-rules"]

Complete guides: Customization Overview

Custom exporters

Add support for new agents by creating custom exporters.

Extension guide: Adding Exporters

Migrating existing rules

Copy rules from existing agent files to AlignTrue.

Manual migration

Create or open a file under .aligntrue/rules/ and paste your existing rules from agent files (Cursor .mdc, AGENTS.md, etc.). Keep exports read-only.

# After copying rules into .aligntrue/rules/imported.md (for example)
aligntrue sync

Next steps: Natural Markdown Sections

Workflow examples

Solo developer workflow

# Daily workflow
cd your-project
vim .aligntrue/rules/base.md  # Edit rules at the source
aligntrue sync           # Update agents
git add .
git commit -m "Update project rules"

Team workflow

# Repository owner
aligntrue team enable
aligntrue sync
git add .aligntrue/
git commit -m "Add AlignTrue configuration"
git push
 
# Team member
git pull
aligntrue sync  # Validates against lockfile

Multi-project workflow

# Create shared rules in a separate repo
cd shared-rules
aligntrue init
# Add rules that apply to all projects
git add . && git commit -m "Add shared rules"
 
# Use in projects - add as connected source
cd project-1
aligntrue add source ../shared-rules
aligntrue sync

Troubleshooting

Common issues and solutions:

Rules not showing in agent?

  • Check agent is enabled in .aligntrue/config.yaml
  • Run aligntrue sync again
  • Restart your IDE

Syntax errors?

  • Run aligntrue check for validation
  • Run aligntrue md lint for markdown issues

Network consent prompts?

  • First-time git source access requires consent
  • Use --offline flag to skip network operations
  • Run aligntrue privacy grant git to enable network access

Full troubleshooting: Troubleshooting Guide

Learning resources

Guides

Reference

Contributing

Community

Need help?

Want to contribute?

Ready to dive deeper? Pick a topic from the guides above and explore AlignTrue’s full capabilities.

Last updated on
QuickstartSolo vs. team mode