Team guide

This guide shows how teams use AlignTrue to maintain consistent AI agent behavior across team members with reproducible builds, drift detection, and approval workflows.

Quick start guide for team collaboration. For comprehensive reference on team mode features and configuration, see Team Mode Concepts.

See it in action: Check out the team repo example for team workflows, and overlays example for customization patterns.

Quick team setup


# 1. Enable team mode
aligntrue team enable
 
# 2. Generate lockfile
aligntrue sync
 
# 3. Commit team config and lockfile (approval via PR review)
git add .aligntrue/config.team.yaml .aligntrue/lock.json
git commit -m "chore: Enable AlignTrue team mode"
git push origin main

Result: Team gets reproducible builds with drift detection.

Two-file config system

When you enable team mode, AlignTrue creates two config files:

File	Purpose	Git status
`config.team.yaml`	Team settings (exporters, sources, lockfile on)	Committed
`config.yaml`	Personal settings (personal remote, local overrides)	Gitignored

This separation means:

No merge conflicts on personal settings like remotes.personal
Easy local overrides (e.g., set git.mode: ignore for testing)
Personal rules route to personal remote automatically
Team settings are shared and reviewed via PR

New team members: run aligntrue team join to create your personal (gitignored) config.yaml.

Routing cheatsheet (team mode)

Rule scope	Default push target	Lockfile	Config file for remote
`team`	Stays in repo	Included	n/a (not pushed)
`shared`	`remotes.shared`	Included	Team (or personal if you publish)
`personal`	`remotes.personal`	Excluded	Personal

Notes:

One scope per rule. Use remotes.custom[] for extra destinations; custom remotes are additive to scope routing and concatenate across team + personal configs.
Sources with personal: true mark all imported rules as scope: personal and gitignore them.
Solo mode routes all rules to remotes.personal (unless scope: shared with a shared remote). See Rule sharing & privacy for mode-based routing.

Team mode features

What you get:

Lockfile (v2) - Reproducible builds via a single bundle_hash over team rules + team config
Drift detection - Compares current bundle hash to lockfile bundle hash (lockfile-only category)
Audit trail - Track who changed what and when (via git + lockfile updates)
Git-native workflows - Source approval via PR review

What changes from solo mode:

Lockfile enabled (deterministic bundle hash)
Drift detection via aligntrue drift (CI gates with --gates)
Source approval via git PR workflow

Organizing rules for teams

Teams often need to organize rules differently than solo developers:

Multi-file by concern (recommended for teams)

Best for: Teams, 20+ rules, clear ownership needs

Store rules in logically organized files in .aligntrue/rules/:


project/
├── .aligntrue/
│   ├── config.yaml
│   └── rules/
│       ├── architecture.md
│       ├── security.md
│       ├── testing.md
│       └── documentation.md
├── .cursor/
│   └── rules/  ← Auto-generated from rules/
└── AGENTS.md  ← Auto-generated from rules/

Setup:


mkdir -p .aligntrue/rules
# Create individual rule files for each concern
aligntrue sync

Benefits:

Clear ownership (assign CODEOWNERS per file)
Reduced merge conflicts
Easier to review changes
Better for code reviews (smaller diffs)

Monorepo scopes (context-specific rules)

Use scopes to apply different rules to different directories:


# .aligntrue/config.team.yaml
sources:
  - type: local
    path: .aligntrue/rules
 
scopes:
  - path: "apps/web"
    inherit: true # Includes root rules
  - path: "apps/api"
    inherit: true
  - path: "packages/shared"
    inherit: false # Isolated: no parent rules

Each scope gets its own AGENTS.md or .cursor/rules/ with:

Root rules (from .)
Scope-specific rules (from apps/web/, etc.)

When to use: Monorepos with multiple apps/services that need context-specific rules.

CODEOWNERS for approval:


# .github/CODEOWNERS
.aligntrue/rules/architecture.md @architects
.aligntrue/rules/security.md @security-team
.aligntrue/rules/testing.md @qa-team

This ensures the right team approves rule changes.

Team setup workflow

Step 1: Enable team mode


cd your-repo
aligntrue team enable

What it does:

Creates .aligntrue/lock.json (lockfile)
Sets mode to team in config
Enables lockfile (deterministic bundle hash)
Source approval happens via git PR workflow

Step 2: Configure sources

Add sources to .aligntrue/config.team.yaml:


sources:
  - type: git
    url: https://github.com/AlignTrue/aligntrue
    path: examples/aligns/global.yaml
  - type: git
    url: https://github.com/org/standards
    path: typescript-standards.yaml

Note: Source approval happens via git PR review workflow.

Step 3: Generate lockfile (v2)


aligntrue sync

Lockfile structure (v2):


{
  "version": "2",
  "bundle_hash": "sha256:abc123... (team rules + config.team.yaml)"
}

Step 4: Commit to git


git add .aligntrue/ .aligntrue/lock.json
git commit -m "chore: Enable AlignTrue team mode"
git push

What to commit:

.aligntrue/rules - Source-of-truth rule files you author
.aligntrue/config.team.yaml - Team configuration
.aligntrue/lock.json - Lockfile with pinned hashes
Agent exports (.cursor/rules/, AGENTS.md, etc.) are generated artifacts. Default git mode for solo/team is ignore, so they are typically gitignored. Commit only when required (compliance snapshot, downstream handoff without AlignTrue) or set per-exporter overrides.

Also do not commit:

.aligntrue/config.yaml - Personal overrides (gitignored)

What NOT to commit:

.aligntrue/.cache/ - Cache directory
.aligntrue/privacy-consent.json - Per-machine consent

Collaboration scenarios

Scenario 1: Onboarding new team members

Goal: New developer gets exact same rules as team.

Steps:


# 1. Clone repo
git clone https://github.com/org/project
cd project

Install CLI:

npm

bash npm install -g aligntrue

yarn

bash yarn global add aligntrue

pnpm

bash pnpm add -g aligntrue

bun

bash bun install -g aligntrue

Sync (uses lockfile):


aligntrue sync
 
# Output:
# ✓ Pulled 3 sources
# ✓ Applied 2 overlays
# ✓ Lockfile updated
# ✓ Exported to cursor, agents

Result: New developer has identical rules as team (byte-identical exports).

Goal: Maintain team-specific standards across projects.

Setup:


# 1. Create team standards repo
mkdir team-standards
cd team-standards
git init
 
# 2. Create rules align
cat > rules.yaml <<EOF
id: team-standards
version: 1.0.0
spec_version: "1"
profile:
  id: org/team-standards
  version: 1.0.0
 
rules:
  - id: team.no-console-log
    summary: No console.log in production
    severity: error
    guidance: Use proper logging library
    applies_to: ["**/*.ts"]
 
plugs:
  slots:
    test.cmd:
      description: "Team test command"
      format: command
      required: true
      example: "pnpm test"
  fills:
    test.cmd: "pnpm test"  # Team default
EOF
 
# 3. Commit and push
git add rules.yaml
git commit -m "Initial team standards"
git push
 
# 4. Use in projects
cd ~/projects/team-project
aligntrue init
 
# Add to .aligntrue/rules:
sources:
  - git: https://github.com/org/team-standards
    ref: v1.0.0
 
# 5. Sync and commit (approval via PR)
aligntrue sync
git add .aligntrue/ .aligntrue/lock.json
git commit -m "Add team standards"
git push origin main

Result: All team projects use shared standards.

Scenario 3: Customizing for team needs

Goal: Use upstream align but adjust severity for team preferences.

Setup:


# .aligntrue/rules
sources:
  - git: https://github.com/community/typescript-align
    ref: v1.0.0
 
# Team prefers stricter enforcement
overlays:
  overrides:
    # Team policy: No console.log (approved 2025-10-15)
    - selector: "rule[id=no-console-log]"
      set:
        severity: "error" # Upgrade from warning
 
    # Team policy: No any types (approved 2025-10-15)
    - selector: "rule[id=no-any-type]"
      set:
        severity: "error" # Upgrade from warning

Workflow:


# 1. Team lead adds overlays
# (edit .aligntrue/rules)
 
# 2. Sync and test
aligntrue sync
aligntrue check
 
# 3. Commit with team approval
git add .aligntrue/
git commit -m "chore: Enforce stricter console.log and any-type rules
 
Approved by: @team-lead
Reviewed by: @senior-dev1, @senior-dev2"
git push
 
# 4. Team members pull and sync
git pull
aligntrue sync

Result: Team uses customized align without forking.

Scenario 4: Monorepo with multiple teams

Goal: Different teams own different parts of monorepo with team-specific rules.

Structure:


company-monorepo/
├── apps/
│   ├── web/          # Team A: Frontend
│   └── mobile/       # Team B: Mobile
├── packages/
│   ├── api/          # Team C: Backend
│   └── shared/       # Shared utilities
└── services/
    └── worker/       # Team D: Workers

Configuration:


# .aligntrue/rules
sources:
  - git: https://github.com/company/base-standards
    ref: v2.0.0
  - git: https://github.com/company/frontend-standards
    ref: v1.0.0
  - git: https://github.com/company/backend-standards
    ref: v1.0.0
 
scopes:
  # Team A: Frontend (owner: @frontend-team)
  - path: "apps/web"
    include: ["**/*.ts", "**/*.tsx"]
    rulesets: ["base-standards", "frontend-standards"]
 
  # Team B: Mobile (owner: @mobile-team)
  - path: "apps/mobile"
    include: ["**/*.ts", "**/*.tsx"]
    rulesets: ["base-standards", "frontend-standards"]
 
  # Team C: Backend (owner: @backend-team)
  - path: "packages/api"
    include: ["**/*.ts"]
    rulesets: ["base-standards", "backend-standards"]
 
  # Shared: Base only (owner: @platform-team)
  - path: "packages/shared"
    include: ["**/*.ts"]
    rulesets: ["base-standards"]
 
# Team-specific plugs
plugs:
  fills:
    test.cmd: "pnpm test"
    org.name: "Acme Corp"
 
# Team-specific overlays
overlays:
  overrides:
    # Company policy: No console.log
    - selector: "rule[id=no-console-log]"
      set:
        severity: "error"

Workflow:


# 1. Enable team mode
aligntrue team enable
 
# 2. Sync and verify
aligntrue sync
aligntrue scopes
 
# 3. Commit (approval via PR)
git add .aligntrue/ .aligntrue/lock.json
git commit -m "chore: Configure team scopes and standards"
git push origin main

Result: Each team gets appropriate rules while sharing base standards.

Scenario 5: Updating upstream Aligns

Goal: Update to new version of upstream align safely.

Workflow:


# 1. Check for drift
aligntrue drift
 
# Output:
# Upstream drift detected:
#   git:https://github.com/AlignTrue/aligntrue/examples/aligns/global.yaml
#   - Current: sha256:abc123...
#   - Latest: sha256:def456...
#   - Changes: 3 new rules, 2 modified rules
 
# 2. Test with team
aligntrue check
aligntrue sync
 
# 3. Commit changes
git add .aligntrue/lock.json
git commit -m "chore: Update approved rule sources"
git push

Result: Team stays synchronized with approved external sources through git-native PR reviews.

Drift detection

Team mode provides comprehensive drift detection to catch misalignment early. The aligntrue drift command detects three types of drift:

1. Lockfile drift

What it detects: Rules have changed since last lockfile generation.

When it happens:

Someone edited .aligntrue/rules directly
Bundle dependencies changed
Source rules updated outside of .aligntrue/rules/

How to detect:


aligntrue drift
 
# Output:
# LOCKFILE DRIFT:
#   _bundle
#     Rules have changed since last lockfile generation
#     Old bundle: sha256:abc123...
#     New bundle: sha256:def456...
#     Suggestion: Run: aligntrue sync (to regenerate lockfile)

How to resolve:


# Regenerate lockfile with new bundle hash
aligntrue sync
 
# Commit the updated lockfile (approval via PR)
git add .aligntrue/lock.json
git commit -m "chore: Update lockfile after rule changes"
git push origin main

Lockfile enabled by default in team mode:


# .aligntrue/config.team.yaml
modules:
  lockfile: true # Enabled by default

CI enforcement:

Use aligntrue drift --gates in CI to fail the pipeline when lockfile drift is detected:


# CI workflow
- run: aligntrue sync --yes
- run: aligntrue drift --gates # Fails if drift detected

2. Agent file drift

What it detects: Agent files (AGENTS.md, .cursor/rules/*.mdc) checksums don’t match previous exports.

When it happens:

Agent files are manually edited directly (outside of AlignTrue)
Sync process detects unexpected changes

Why it matters: In team mode, agent files are exports from IR (.aligntrue/rules), which is the single source of truth. Manual edits to agent files are backed up and overwritten to maintain consistency.

How to detect:


aligntrue drift
# Shows if agent files have been manually edited since last sync

How to resolve:


# Sync IR to agents (overwrites manual edits with clean IR content)
aligntrue sync
 
# Backups of manually edited content saved to .aligntrue/.backups/files/
ls .aligntrue/.backups/files/

Best practice: Always edit rules in .aligntrue/rules/, never directly edit agent files in team mode. Agent files are always generated exports.

3. Upstream drift

What it detects: Upstream align content changed since lockfile generation.

When it happens:

Upstream align repository updated
New version published to catalog
Git source ref changed

How to detect:


aligntrue drift
 
# Output:
# UPSTREAM DRIFT:
#   git:https://github.com/AlignTrue/aligntrue/examples/aligns/global.yaml
#     Upstream align has been updated (base_hash differs)
#     Lockfile: sha256:abc123...
#     Allowed: sha256:def456...
#     Suggestion: Pull latest from source and sync

How to resolve:


# Pull latest from approved sources
git pull
 
# Sync to regenerate lockfile
aligntrue sync
 
# Commit changes (approval via PR)
git add .aligntrue/lock.json
git commit -m "chore: Update lockfile after upstream changes"
git push origin main

Drift detection in CI

Exit codes:


aligntrue drift          # Exit 0 (always)
aligntrue drift --gates  # Exit 2 if drift detected

CI integration:


# .github/workflows/pr.yml
- name: Detect drift
  run: aligntrue drift --gates
# Fails PR if any drift detected

JSON output for tooling:


aligntrue drift --json
 
# Output:
{
  "mode": "team",
  "has_drift": true,
  "lockfile_path": ".aligntrue/lock.json",
  "findings": [
    {
      "category": "lockfile",
      "ruleId": "_bundle",
      "description": "Rules have changed since last lockfile generation",
      "suggestion": "Run: aligntrue sync (to regenerate lockfile)",
      "lockfile_hash": "abc123...",
      "expected_hash": "def456..."
    }
  ],
  "summary": {
    "total": 1,
    "by_category": {
      "lockfile": 1,
      "agent_file": 0,
      "upstream": 0,
      "severity_remap": 0
    }
  }
}

Drift detection best practices

1. Run drift checks regularly:


# Before starting work
aligntrue drift
 
# Before committing
aligntrue drift --gates

2. Set up automated drift detection:


# .github/workflows/drift.yml
name: Drift Detection
 
on:
  schedule:
    - cron: "0 9 * * MON" # Every Monday at 9am
 
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install AlignTrue CLI
        run: npm install -g aligntrue
      - name: Check for drift
        run: aligntrue drift --gates

3. Document drift resolution in commits:


git commit -m "fix: Resolve lockfile drift
 
- Regenerated lockfile after rule changes
- Approved new bundle hash: sha256:abc123...
- Tested with: aligntrue check && aligntrue sync"

4. Enforce drift in CI:


# .github/workflows/ci.yml
- name: Check for drift
  run: aligntrue drift --gates # Fails CI if drift detected

5. Review drift in PRs:


# .github/workflows/pr.yml
- name: Detect drift
  run: |
    aligntrue drift --json > drift-report.json
    cat drift-report.json
 
- name: Comment on PR
  if: failure()
  uses: actions/github-script@v6
  with:
    script: |
      const fs = require('fs');
      const drift = JSON.parse(fs.readFileSync('drift-report.json'));
 
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: `⚠️ Drift detected:\n\`\`\`json\n${JSON.stringify(drift, null, 2)}\n\`\`\``
      });

Customization patterns

Plugs: team-specific values

Use plugs for:

Organization name
Team-specific test commands
Shared documentation URLs

Example:


plugs:
  fills:
    org.name: "Acme Corp"
    test.cmd: "pnpm test"
    docs.url: "https://docs.acme.com"

Workflow:


# Team lead sets fills
aligntrue plugs set org.name "Acme Corp"
aligntrue plugs set test.cmd "pnpm test"
 
# Commit
git add .aligntrue/config.team.yaml
git commit -m "chore: Set team plug values"

Overlays: team severity preferences

Use overlays for:

Team-wide severity adjustments
Customizing third-party Aligns to team standards
Temporary overrides during migrations

Example:


overlays:
  overrides:
    # Team policy: Stricter than upstream
    # Approved: 2025-10-15
    # Owner: @platform-team
    - selector: "rule[id=no-console-log]"
      set:
        severity: "error"
 
    # TEMPORARY: Migration in progress
    # Expires: 2025-12-31
    # Owner: @backend-team
    - selector: "rule[id=strict-null-checks]"
      set:
        severity: "warn"

Workflow:


# Team lead adds overlay
aligntrue override add \
  --selector 'rule[id=no-console-log]' \
  --set severity=error
 
# Review and commit
aligntrue override status
git add .aligntrue/config.team.yaml
git commit -m "chore: Enforce no-console-log as error
 
Approved by: @team-lead
Reviewed by: @senior-dev1, @senior-dev2"

Scopes: team boundaries

Use scopes for:

Team ownership boundaries in monorepo
Different tech stacks per team
Shared base + team-specific overrides

Example:


scopes:
  # Team A owns frontend
  # Owner: @frontend-team
  - path: "apps/web"
    rulesets: ["base-standards", "frontend-standards"]
 
  # Team B owns backend
  # Owner: @backend-team
  - path: "packages/api"
    rulesets: ["base-standards", "backend-standards"]

CI/CD integration

Validate lockfile in CI


# .github/workflows/ci.yml
name: CI
 
on: [push, pull_request]
 
jobs:
  aligntrue:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Install AlignTrue CLI
        run: npm install -g aligntrue
 
      - name: Validate lockfile
        run: aligntrue check --ci
 
      - name: Detect drift
        run: aligntrue drift --gates

What it validates:

Lockfile exists and is valid
No drift from lockfile
All required plugs filled

Detect drift automatically


# .github/workflows/drift.yml
name: Drift Detection
 
on:
  schedule:
    - cron: "0 9 * * MON" # Every Monday at 9am
 
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Install AlignTrue CLI
        run: npm install -g aligntrue
 
      - name: Check for drift
        run: aligntrue drift --json > drift-report.json
 
      - name: Create issue if drift detected
        if: failure()
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const drift = JSON.parse(fs.readFileSync('drift-report.json'));
 
            github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: 'AlignTrue drift detected',
              body: `Drift detected:\n\`\`\`json\n${JSON.stringify(drift, null, 2)}\n\`\`\``,
              labels: ['aligntrue', 'drift']
            });

Block unapproved sources


# .github/workflows/pr.yml
name: PR Checks
 
on: pull_request
 
jobs:
  aligntrue:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Install AlignTrue CLI
        run: npm install -g aligntrue
 
      - name: Validate configuration
        run: |
          # Validate schema and lockfile
          aligntrue check --ci

Team workflows

PR review checklist

When reviewing AlignTrue changes:

Lockfile updated if sources changed
Overlays documented with reason and owner
Plugs filled for required slots
Scopes validated with aligntrue scopes
Changes tested locally with aligntrue sync
CI passes with aligntrue check --ci

Example PR description:


## Changes
 
- Add TypeScript standards align
- Customize severity for team preferences
- Set team-specific plug values
 
## AlignTrue checklist
 
- [x] Lockfile updated
- [x] Overlays documented
- [x] Plugs filled
- [x] CI passes
 
## Testing
 
```bash
aligntrue sync
aligntrue check
```

Tested by: @dev1, @dev2



### Handling conflicts

**Scenario:** Two developers modify rules simultaneously.

**Resolution:**

```bash
# 1. Pull latest
git pull origin main

# Conflict in AGENTS.md or .aligntrue/config.team.yaml

# 2. Resolve conflict manually
# (edit AGENTS.md or .aligntrue/config.team.yaml)

# 3. Regenerate lockfile
aligntrue sync

# 4. Validate
aligntrue check

# 5. Commit resolution
git add AGENTS.md .aligntrue/ .aligntrue/lock.json
git commit -m "chore: Resolve AlignTrue conflict"

Emergency overrides (—force)

When to use:

Production incident requires immediate rule change
Drift detection blocking critical deployment

Workflow:


# 1. Override validation
aligntrue sync --force
 
# 2. Deploy fix
# ... deploy ...
 
# 3. Fix properly afterward
aligntrue sync
git add .aligntrue/lock.json
git commit -m "chore: Update lockfile"
git push origin main
 
# 4. Document in postmortem

Warning: Use --force sparingly. It bypasses safety checks.

Best practices

Document customization decisions

Always explain why using comments:


overlays:
  overrides:
    # Team policy: No console.log in production
    # Approved: 2025-10-15 by @team-lead
    # Reviewed: @senior-dev1, @senior-dev2
    # Reason: Enforce proper logging library usage
    - selector: "rule[id=no-console-log]"
      set:
        severity: "error"

Review overlays periodically

Monthly overlay review:


# 1. Audit all overlays
aligntrue override status
 
# 2. Check for stale overlays
aligntrue override diff
 
# 3. Remove unnecessary overlays
aligntrue override remove 'rule[id=...]'
 
# 4. Document review
git commit -m "chore: Monthly overlay review - removed 3 stale overlays"

Review sources carefully

Only add sources you trust. Changes to sources: in config go through standard git PR review.

Version control everything

Commit all team configuration:


git add .aligntrue/ .aligntrue/lock.json
git commit -m "chore: Update AlignTrue configuration"

Communicate changes

Use PR descriptions and commit messages to explain changes:


git commit -m "chore: Update TypeScript standards to v2.0.0
 
Changes:
- Added 3 new security rules
- Upgraded testing.require-tests to error
- Extended docs.require-readme to all markdown files
 
Impact: All TypeScript files now require tests
Action required: Add tests to new files
 
Approved by: @team-lead
Tested by: @dev1, @dev2, @dev3"

Customization Overview - Plugs, overlays, and scopes
Plugs Guide - Team-specific values
Overlays Guide - Team severity preferences
Scopes Guide - Team boundaries in monorepo
Team Mode - Team mode concepts
Drift Detection - Drift detection details
CLI Reference - Complete command docs
Solo Developer Guide - Solo workflow

Summary

Team collaboration workflow:

Enable team mode - aligntrue team enable
Configure sources - Add to .aligntrue/config.team.yaml
Generate lockfile - aligntrue sync
Commit to git - Share with team (approval via PR)
Onboard members - git clone && aligntrue sync
Update safely - aligntrue drift --gates && aligntrue sync

Key principles:

Reproducible builds with lockfile
Drift detection for upstream changes
Document all customizations
Review changes in PRs
Validate in CI

Next steps:

Team guide

Quick team setup

Two-file config system

Routing cheatsheet (team mode)

Team mode features

Organizing rules for teams

Multi-file by concern (recommended for teams)

Team setup workflow

Step 1: Enable team mode

Step 2: Configure sources

Step 3: Generate lockfile (v2)

Step 4: Commit to git

Collaboration scenarios

Scenario 1: Onboarding new team members

npm

yarn

pnpm

bun

Scenario 2: Sharing team standards

Scenario 3: Customizing for team needs

Scenario 4: Monorepo with multiple teams

Scenario 5: Updating upstream Aligns

Drift detection

1. Lockfile drift

2. Agent file drift

3. Upstream drift

Drift detection in CI

Drift detection best practices

Customization patterns

Plugs: team-specific values

Overlays: team severity preferences

Scopes: team boundaries

CI/CD integration

Validate lockfile in CI

Detect drift automatically

Block unapproved sources

Team workflows

PR review checklist

Emergency overrides (—force)

Best practices

Document customization decisions

Review overlays periodically

Review sources carefully

Version control everything

Communicate changes

Related documentation

Summary