Migration guide

Step-by-step guide for migrating from existing agent configurations to AlignTrue.

Overview

AlignTrue can import rules from multiple agents automatically. This guide covers:

• Cursor (.cursor/*.mdc files)
• AGENTS.md (universal format)
• Aider (.aider.conf.yml)
• VS Code MCP (.vscode/mcp.json)
• Other agent formats

Quick migration

1. Initialize with import

# AlignTrue detects existing configs and offers import
npx aligntrue init
 
# Or explicitly import from specific agent
aligntrue init --import cursor

2. Review imported rules

# Check what was imported in the internal IR
cat .aligntrue/.rules.yaml
 
# Validate all rules
aligntrue check

3. Sync to all agents

aligntrue sync

Done! Your rules are now managed by AlignTrue and synced to all agents. Edit AGENTS.md or any agent file to make changes.

Agent-specific migration

Migrating from Cursor

Before AlignTrue:

.cursor/
  rules/
    global.mdc
    project.mdc
    testing.mdc

Migration steps:

1. Initialize with import:

aligntrue init --import cursor

2. Review imported rules:

cat .aligntrue/.rules.yaml

AlignTrue imports all .mdc files, merges them into the IR, and creates AGENTS.md as the user-editable interface.

3. Sync back to Cursor:

aligntrue sync

After AlignTrue:

.aligntrue/
  .rules.yaml       # Internal IR (auto-generated)
  config.yaml       # Configuration
AGENTS.md           # User-editable (primary editing interface)
.cursor/
  rules/
    aligntrue.mdc   # Generated by AlignTrue

Benefits:

• Edit rules in AGENTS.md or agent-native formats
• Sync same rules to other agents
• Version control with git
• Team collaboration with lockfiles
• Two-way sync keeps everything aligned

Migrating from GitHub Copilot / Claude Code

Before AlignTrue:

AGENTS.md  # Universal format

Migration steps:

1. Initialize with import:

aligntrue init --import agents-md

2. Review imported rules:

cat .aligntrue/.rules.yaml

3. Sync to all agents:

aligntrue sync

After AlignTrue:

.aligntrue/
  .rules.yaml       # Internal IR (auto-generated)
  config.yaml       # Configuration
AGENTS.md           # Primary user-editable file
.cursor/
  rules/
    aligntrue.mdc   # Also generated if Cursor detected

Benefits:

• Keep AGENTS.md format
• Add support for Cursor and other agents
• Two-way sync (edit either file)

Migrating from Aider

Before AlignTrue:

.aider.conf.yml

Migration steps:

1. Initialize with import:

aligntrue init --import aider

2. Review imported rules:

cat .aligntrue/.rules.yaml

3. Sync to all agents:

aligntrue sync

After AlignTrue:

.aligntrue/
  .rules.yaml       # Internal IR (auto-generated)
  config.yaml
AGENTS.md           # Primary editing file (Aider reads this)
.aider.conf.yml     # Generated by AlignTrue

Note: Edit AGENTS.md, AlignTrue syncs to all agent formats.

Migrating from VS Code MCP

Before AlignTrue:

.vscode/
  mcp.json

Migration steps:

1. Initialize with import:

aligntrue init --import vscode-mcp

2. Review imported rules:

cat .aligntrue/.rules.yaml

3. Sync to all agents:

aligntrue sync

After AlignTrue:

.aligntrue/
  .rules.yaml       # Internal IR (auto-generated)
  config.yaml
AGENTS.md           # Primary editing file
.vscode/
  mcp.json          # Generated by AlignTrue

Migrating from multiple agents

Before AlignTrue:

.cursor/rules/*.mdc
AGENTS.md
.aider.conf.yml

Migration steps:

1. Initialize (detects all):

aligntrue init

You’ll be prompted:

✓ Detected existing configs:
  - Cursor (.cursor/rules/*.mdc)
  - AGENTS.md
  - Aider (.aider.conf.yml)

? Import rules from these sources? (Y/n)

2. AlignTrue merges all sources:

• Deduplicates identical rules
• Preserves agent-specific settings in vendor.* namespace
• Creates unified AGENTS.md and .aligntrue/.rules.yaml

3. Review merged rules:

cat AGENTS.md

4. Sync to all agents:

aligntrue sync

After AlignTrue:

.aligntrue/
  .rules.yaml       # Internal IR (auto-generated)
  config.yaml
AGENTS.md           # Merged from all sources (edit this)
.cursor/rules/aligntrue.mdc
.aider.conf.yml     # Generated by AlignTrue

Import command reference

Basic import

# Import from detected agent
aligntrue import cursor
 
# Creates AGENTS.md immediately
aligntrue import cursor --write
 
# Preview without writing
aligntrue import cursor --dry-run

Coverage analysis

# Show what will be imported
aligntrue import cursor --coverage

Output:

Coverage Analysis
─────────────────

Source: .cursor/rules/global.mdc
  ✓ 5 rules imported
  ✓ 2 agent-specific settings preserved

Source: .cursor/rules/project.mdc
  ✓ 3 rules imported
  ⚠ 1 rule skipped (duplicate)

Total: 8 rules imported, 1 skipped

Supported agents

aligntrue import --list

Output:

Supported import sources:
  - cursor          .cursor/rules/*.mdc
  - agents-md       AGENTS.md
  - aider           .aider.conf.yml
  - vscode-mcp      .vscode/mcp.json
  - windsurf        .windsurf/mcp_config.json

Handling conflicts

Duplicate rules

If multiple sources have the same rule, AlignTrue:

1. Imports the first occurrence
2. Skips duplicates
3. Reports in coverage analysis

Example:

⚠ Rule "use-typescript" found in:
  - .cursor/rules/global.mdc (imported)
  - AGENTS.md (skipped, duplicate)

Agent-specific settings

Agent-specific settings are preserved in vendor.* namespace:

rules:
  - id: use-typescript
    content: "Always use TypeScript"
    vendor:
      cursor:
        priority: high

These settings are excluded from hashing but preserved on sync.

Conflicting rule content

If the same rule ID has different content:

⚠ Conflict detected:
  Rule: use-typescript
  Source 1: .cursor/rules/global.mdc
    "Always use TypeScript with strict mode"
  Source 2: AGENTS.md
    "Prefer TypeScript"

? Which version to keep?
  > Source 1 (.cursor/rules/global.mdc)
    Source 2 (AGENTS.md)
    Merge manually

Post-migration checklist

1. Validate rules

aligntrue check

2. Test sync

aligntrue sync --dry-run

3. Verify agent files

Check that generated files look correct:

cat .cursor/rules/aligntrue.mdc
cat AGENTS.md

4. Test in your IDE

1. Restart your IDE (Cursor, VS Code, etc.)
2. Verify rules are loaded
3. Test AI agent behavior

5. Commit to git

git add .aligntrue/
git commit -m "feat: Migrate to AlignTrue"

6. Clean up old files (optional)

If you’re confident everything works:

# Remove old Cursor rules (AlignTrue generates new ones)
rm -rf .cursor/rules/*.mdc
# Keep .cursor/rules/aligntrue.mdc
 
# Remove old Aider config (if using AGENTS.md)
rm .aider.conf.yml

Important: Don’t delete files until you’ve verified AlignTrue works!

Rollback

If you need to rollback:

1. Restore from git

git restore .cursor/ AGENTS.md .aider.conf.yml

2. Remove AlignTrue

rm -rf .aligntrue/

3. Uninstall CLI (optional)

npm uninstall -g @aligntrue/cli

Common migration scenarios

Scenario 1: Solo developer with Cursor

Goal: Keep using Cursor, add support for other agents

Steps:

1. aligntrue init --import cursor
2. aligntrue sync
3. Keep editing AGENTS.md or .cursor/*.mdc (two-way sync)

Scenario 2: Team with AGENTS.md

Goal: Add team mode with lockfiles

Steps:

1. aligntrue init --import agents-md
2. aligntrue team enable
3. Commit .aligntrue.lock.json to git
4. Team members run aligntrue sync

Scenario 3: Multiple agents, consolidate

Goal: Merge rules from Cursor, Aider, and AGENTS.md

Steps:

1. aligntrue init (detects all)
2. Review merged rules in AGENTS.md
3. aligntrue sync
4. Remove old config files after verification

Scenario 4: Fresh start, keep old rules as reference

Goal: Start fresh but reference old rules

Steps:

1. Backup old configs: cp -r .cursor .cursor.bak
2. aligntrue init (don’t import)
3. Manually copy rules you want from .cursor.bak
4. aligntrue sync

Troubleshooting migration

Import fails with “No rules found”

Cause: Agent config files are empty or invalid

Fix:

1. Check files exist: ls .cursor/rules/
2. Check files have content: cat .cursor/rules/*.mdc
3. Validate format (must be valid MDC/YAML)

Imported rules don’t sync to agent

Cause: Exporter not enabled

Fix:

# Check enabled exporters
cat .aligntrue/config.yaml | grep exporters -A 5
 
# Enable if missing
aligntrue sync --target cursor

Rules work in Cursor but not Copilot

Cause: Different format requirements

Fix:

1. Check AGENTS.md was generated: cat AGENTS.md
2. Verify format is correct
3. Restart IDE

Lockfile immediately shows drift

Cause: Volatile fields included in hash

Fix:

# .aligntrue/config.yaml
vendor:
  _meta:
    volatile: ["cursor.timestamp", "cursor.session"]

Next steps

After migration:

• Workflows guide - Choose your workflow
• Team mode - Enable team features
• Git workflows - Share rules via git

See also

• Import workflow reference - Detailed import documentation
• Sync behavior - How sync works
• Troubleshooting - Common issues