Joining an Existing Team

This guide walks you through joining a project that already uses AlignTrue in team mode.

Prerequisites

• AlignTrue CLI installed (npm install -g @aligntrue/cli)
• Access to the team’s repository
• Git configured with your credentials

Step 1: Clone the Repository

git clone git@github.com:yourteam/project.git
cd project

Step 2: Initialize AlignTrue

Run the init command:

aligntrue init

AlignTrue will detect the existing team configuration and show you a summary:

✓ Detected team mode configuration

Team Configuration:
  Mode: team
  Approval: pr_approval (relaxed)
  Team sections: Security, Compliance, Architecture

Your Options:
  1. Use team rules only (no personal rules)
  2. Add personal rules (local only)
  3. Add personal rules (with remote backup)

Option 1: Team Rules Only

Select this if you don’t need any personal rules:

aligntrue init --team-only

This is the simplest setup. All rules come from the team repository.

Option 2: Personal Rules (Local)

Select this if you want personal rules but don’t need version control:

aligntrue init --with-personal-local

Your personal rules will be stored in .aligntrue/.local/personal/ and git-ignored.

Option 3: Personal Rules (Remote)

Select this if you want personal rules with version control and backup:

aligntrue init --with-personal-remote

You’ll be prompted to set up a remote repository. See Personal Repository Setup for details.

Step 3: Initial Sync

After initialization, sync the rules to your agent files:

aligntrue sync

This will:

1. Load team rules from the repository
2. Load your personal rules (if configured)
3. Merge them together
4. Export to agent files (.cursor/rules/*.mdc, AGENTS.md, etc.)

Step 4: Verify Setup

Check that rules were exported correctly:

# List generated files
ls -la .cursor/rules/
cat AGENTS.md
 
# Check configuration
aligntrue config

Understanding Team Mode

Team Rules

Team rules are:

• Stored in .aligntrue/.rules.yaml in the main repository
• Committed to version control
• Visible to all team members
• Require approval to change (depending on mode)

Personal Rules

Personal rules are:

• Stored locally or in a private remote
• Not visible to other team members
• Can be changed without approval
• Merged with team rules during sync

Agent Files

Agent files (.cursor/rules/*.mdc, AGENTS.md) are:

• Generated from team + personal rules
• Git-ignored by default (recommended)
• Regenerated on each sync
• Safe to edit locally (changes sync back to IR)

Making Changes

Editing Team Rules

To propose changes to team rules:

1. Edit AGENTS.md or agent files directly
2. Run aligntrue sync
3. Commit the changes to .aligntrue/.rules.yaml
4. Push and create a PR
5. Team lead reviews and approves
6. After merge, everyone runs aligntrue sync to get updates

Editing Personal Rules

To change your personal rules:

1. Edit AGENTS.md or agent files (personal sections)
2. Run aligntrue sync
3. Changes stay local or sync to your personal remote
4. No approval needed

Approval Modes

Your team may use different approval modes:

Relaxed (pr_approval)

• Changes go through normal PR process
• No special AlignTrue approval needed
• CI validates lockfile integrity
• Most common for internal teams

Strict (allowlist)

• Changes must be explicitly approved
• aligntrue drift --gates fails in CI if unapproved
• Team lead runs aligntrue team approve --current
• More common for external dependencies

Check your team’s mode:

aligntrue config get approval.internal

Common Workflows

Daily Sync

Pull latest team rules:

git pull
aligntrue sync

Propose Rule Change

1. Create a branch:

   git checkout -b add-security-rule

2. Edit rules:

   # Edit AGENTS.md or agent files
   aligntrue sync

3. Commit and push:

   git add .aligntrue/.rules.yaml
   git commit -m "feat: Add security scanning rule"
   git push origin add-security-rule

4. Create PR and wait for approval

Update Personal Rules

1. Edit your personal sections in AGENTS.md
2. Run aligntrue sync
3. Changes stay local (no PR needed)

Resolve Drift

If CI reports drift:

# Check what changed
aligntrue drift
 
# If you made the change, ask team lead to approve:
# (Team lead runs) aligntrue team approve --current
 
# Or revert your changes:
git checkout .aligntrue/.rules.yaml
aligntrue sync

Troubleshooting

Sync Fails with “Lockfile Mismatch”

Cause: Your rules don’t match the approved lockfile.

Fix:

# Pull latest changes
git pull
 
# Sync again
aligntrue sync
 
# If still failing, check for local modifications
git status

Personal Rules Not Showing

Cause: Personal rules might not be configured correctly.

Fix:

# Check configuration
aligntrue config get storage.personal
 
# Reconfigure if needed
aligntrue init --with-personal-local

Agent Files Not Generated

Cause: Exporters might not be enabled.

Fix:

# Check enabled exporters
aligntrue adapters list
 
# Enable missing exporters
aligntrue adapters enable cursor
aligntrue adapters enable agents-md
 
# Sync again
aligntrue sync

Remote Personal Repo Fails

Cause: SSH access or repository not configured.

Fix:

See Personal Repository Setup for detailed troubleshooting.

Best Practices

DO

• ✅ Run aligntrue sync after pulling changes
• ✅ Keep agent files git-ignored (recommended)
• ✅ Use personal rules for machine-specific preferences
• ✅ Create PRs for team rule changes
• ✅ Review lockfile changes in PRs

DON’T

• ❌ Commit agent files to the repository
• ❌ Edit .aligntrue/.rules.yaml directly
• ❌ Put personal rules in the main repository
• ❌ Skip sync after pulling changes
• ❌ Force push lockfile changes

Getting Help

If you’re stuck:

1. Check the Troubleshooting Guide
2. Ask your team lead about team-specific configuration
3. Run aligntrue check to validate your setup
4. Check logs: aligntrue sync --verbose

Next Steps

• Understand Team Mode
• Set Up Personal Repository
• Learn About Scopes
• Explore Migration Commands