Rule sharing & privacy

This guide helps you control three independent aspects of your rules: who sees them, whether they need approval, and where they sync.

Quick decision table

Not sure how to configure your rules? Find your use case below:

New to packs? See Align packs for manifest fields, limits, and examples.

Publishing rules (for maintainers)

Setting up a shared rules repository

Create a repository to publish your rules:

1. Create a repository on GitHub, GitLab, or your preferred git host:

   • For public sharing: Create a public repository
   • For team/private sharing: Create a private repository with appropriate access

2. Configure remotes in .aligntrue/config.yaml:

remotes:
  shared: git@github.com:username/shared-rules.git

3. Push your rules (auto by default):

# Default: pushes on every sync unless you set auto: false on the remote
aligntrue sync
 
# If you set auto: false (or want an explicit push)
aligntrue remotes push

4. Share the repository URL with others. They can consume your rules as a source:

# Their config
sources:
  - type: git
    url: https://github.com/username/shared-rules.git
    ref: main

Your rules repository structure

As a rules maintainer:

1. Edit rules locally - Make changes in .aligntrue/rules/
2. Test changes - Run aligntrue sync to verify exports
3. Push to remote - Happens on aligntrue sync by default; set auto: false if you prefer to push manually with aligntrue remotes push

Your rules repository structure:

your-rules-repo/
  typescript.md
  testing.md
  guides/
    react.md
    vue.md

Consumers receive these files when they sync from your repository.

Separating public and private rules

You may want to share some rules publicly while keeping others private. Use multiple remotes:

remotes:
  shared:
    url: git@github.com:username/public-rules.git
  personal:
    url: git@github.com:username/private-rules.git

Then use scope in rule frontmatter to control routing.

Privacy controls

The three dimensions of rule privacy:

These dimensions are largely independent. A rule can be:

• Gitignored but tracked in lockfile
• Personal-scope but committed to the repo
• Gitignored and personal-scope (fully private)
• Shared-scope for publishing

Mode-based routing and auto defaults

• Auto default: Remotes push during aligntrue sync unless you set auto: false on a remote. Use aligntrue remotes push when you want explicit/manual pushes.
• Solo mode routing (default): All rules route to remotes.personal (unless a rule is scope: shared and a shared remote exists). Scope is ignored for personal routing in solo mode.
• Team/enterprise routing: Scope-based:
  • scope: personal → remotes.personal
  • scope: shared → remotes.shared
  • scope: team → stays in repo
• Custom remotes: Additive in all modes; matched files also go to those remotes.

How data flows: Sources vs Remotes

Understanding the difference between sources and remotes is key to setting up your workflow:

Consumer vs Maintainer roles

You can have multiple roles simultaneously with different rules. For example:

• Pull team standards via sources
• Maintain personal preferences locally
• Push personal rules to remotes.personal
• Push curated rules to remotes.shared for your team

Common scenarios

Scenario 1: Keep a rule private to my machine

Use this when the rule is machine-specific or sensitive.

---
title: My SSH Configuration
gitignore: true
scope: personal
---

Result:

• Not committed to git
• Not in lockfile
• Not synced anywhere

Scenario 2: Sync personal rules across my machines

Use this to access the same personal preferences on all your machines.

---
title: My Editor Shortcuts
scope: personal
---

Plus configure .aligntrue/config.yaml:

# Pull personal rules from remote
sources:
  - type: git
    url: git@github.com:yourusername/personal-rules.git
    personal: true
 
# Push personal rules to the same remote
remotes:
  personal: git@github.com:yourusername/personal-rules.git

Result:

• Rules committed to your repo
• Not in team lockfile (won’t trigger drift)
• Pulled from and pushed to your personal remote (auto on by default; set auto: false to require aligntrue remotes push)
• Accessible on all your machines

Scenario 3: Share team rules normally

Use this for shared team standards.

---
title: Team Security Standards
---

No special config needed.

Result:

• Committed to git
• Tracked in lockfile (requires team approval to change)
• Stays in main repo only

Scenario 4: Publish rules for others to use

Use this when you want to share a curated set of rules with your team or the community.

---
title: React Best Practices
scope: shared
---

Plus configure .aligntrue/config.yaml:

remotes:
  shared: git@github.com:yourusername/react-rules-pack.git

Result:

• Committed and tracked in lockfile
• Synced to the shared remote for publishing
• Others can consume via sources

Setting git visibility

Use gitignore: true in rule frontmatter to exclude the rule’s exported files from git (source stays tracked unless you gitignore it or run with git.mode: ignore):

---
title: My Private Notes
gitignore: true
---
# Exported files like `.cursor/rules/my-private-notes.mdc` are auto-added to a managed block in `.gitignore`.
# The source `.aligntrue/rules/my-private-notes.md` remains tracked unless you gitignore it separately.

Git visibility table

Setting approval scope

Use scope in rule frontmatter to control lockfile tracking and remote routing:

---
title: My Preferences
scope: personal
---
# This rule won't trigger lockfile changes

Scope values and behavior

Team-scope rules:

• Tracked in lockfile (changes require approval)
• Stay in main repo only
• Good for shared standards

Personal-scope rules:

• Excluded from lockfile
• Can change freely
• Automatically synced to remotes.personal if configured
• Good for individual preferences

Shared-scope rules:

• Tracked in lockfile (require team approval)
• Synced to remotes.shared for publishing
• Good for rule packs you want to share

Remote routing with sources and remotes

Pulling rules from a remote source

Add a git source using the CLI or config:

CLI:

# Add as a connected source (pulls on sync)
aligntrue add source git@github.com:yourusername/personal-rules.git --personal

Config:

# .aligntrue/config.yaml
sources:
  - type: local
    path: .aligntrue/rules
  - type: git
    url: git@github.com:yourusername/personal-rules.git
    personal: true

The personal: true flag on a source:

• Marks all rules from that source as scope: personal
• Auto-applies gitignore: true
• SSH URLs (git@...) automatically get gitignore: true

Pushing rules to remote repositories

Configure remotes using the CLI or config:

CLI:

# Add personal remote (for scope: personal rules)
aligntrue add remote git@github.com:yourusername/personal-rules.git --personal
 
# Add shared remote (for scope: shared rules)
aligntrue add remote git@github.com:yourusername/shared-rules.git --shared

Config:

# .aligntrue/config.yaml
remotes:
  # Personal-scope rules go here
  personal: git@github.com:yourusername/personal-rules.git
 
  # Shared-scope rules go here (for publishing)
  shared: git@github.com:yourusername/shared-rules.git
 
  # Optional: fine-grained pattern-based routing
  custom:
    - id: typescript
      url: git@github.com:yourusername/typescript-rules.git
      include: ["typescript*.md", "eslint*.md"]

How routing works

1. Scope-based routing (primary): Rules are routed based on their scope frontmatter

   • scope: personal rules → remotes.personal
   • scope: shared rules → remotes.shared
   • scope: team rules → stay in main repo only

2. Custom pattern routing (additive): Use custom for fine-grained control

   • Files matching patterns go to those remotes in addition to scope-based routing
   • A rule can go to multiple destinations

• Useful for creating thematic groups (e.g., all TypeScript rules)

Routing recap (team mode):

FAQs:

• Can one rule be both personal and shared? No. Each rule has one scope. Use remotes.custom[] for extra destinations.
• Where should remotes live? remotes.shared usually in config.team.yaml; remotes.personal in your personal config.yaml. Both files can add remotes.custom and they concatenate.
• Do custom remotes replace scope routing? No. Custom remotes are additive; scope routing still happens.

Using shared rules (for consumers)

Option 1: Link as a source (get updates)

Add the repository as a source to get ongoing updates:

aligntrue add source https://github.com/username/shared-rules.git

Or manually add to config:

sources:
  - type: git
    url: https://github.com/username/shared-rules.git
    ref: main # Or a specific tag/commit for stability

Run aligntrue sync to pull updates.

Option 2: One-time import (copy)

Copy rules to your local .aligntrue/rules/:

aligntrue add https://github.com/username/shared-rules.git

This copies the rules locally. You won’t get updates unless you run add again.

Version pinning

For stability, consumers can pin to a specific version:

sources:
  - type: git
    url: https://github.com/username/shared-rules.git
    ref: v1.2.0 # Pin to tag

Or a specific commit:

sources:
  - type: git
    url: https://github.com/username/shared-rules.git
    ref: abc123def # Pin to commit SHA

Personal rules across machines

Use remotes to sync your personal rules across multiple machines (push from one, pull as a source on another):

Machine A (primary)

remotes:
  personal:
    url: git@github.com:username/my-rules.git

Machine B (secondary)

Option 1: Use as source (pull only):

sources:
  - type: git
    url: git@github.com:username/my-rules.git
    personal: true # Skip team approval

Option 2: Also backup from Machine B:

sources:
  - type: git
    url: git@github.com:username/my-rules.git
    personal: true
 
remotes:
  personal:
    url: git@github.com:username/my-rules.git

With Option 2, edits on either machine will push to the remote. Be careful of conflicts.

Best practices

For maintainers

• Use semantic versioning tags for releases
• Document breaking changes in your repository
• Keep rules focused and well-documented
• Consider separating stable rules from experimental ones

For consumers

• Pin to tags or commits for production use
• Review updates before merging in team mode
• Fork repositories for critical dependencies

General do’s

• Use gitignore: true for rules with sensitive content
• Use scope: personal for individual preferences in team mode
• Use scope: shared for rules you want to publish to others
• Use sources with personal: true to pull personal rules from remote
• Configure remotes.personal to sync personal rules across machines
• Use remotes.shared to publish curated rule packs

General don’ts

• Use scope: personal to bypass team review for shared standards
• Assume gitignored rules are backed up (configure remotes.personal for that)
• Configure the same URL as both a source and a remote (creates conflicts)

Complete workflow example

Setting up personal rules that sync across machines:

Step 1: Create a private repo

# On GitHub, create: aligntrue-personal-rules (private)

Step 2: Configure AlignTrue

Using CLI commands:

# Import existing rules from your personal repo (one-time copy)
aligntrue add git@github.com:yourusername/aligntrue-personal-rules.git
 
# OR add as connected source (pulls updates on sync)
aligntrue add source git@github.com:yourusername/aligntrue-personal-rules.git --personal
 
# Add as push destination
aligntrue add remote git@github.com:yourusername/aligntrue-personal-rules.git --personal

Or configure directly in YAML:

# .aligntrue/config.yaml
sources:
  - type: local
    path: .aligntrue/rules
  - type: git
    url: git@github.com:yourusername/aligntrue-personal-rules.git
    personal: true
 
remotes:
  personal: git@github.com:yourusername/aligntrue-personal-rules.git
 
exporters:
  - cursor
  - agents

Step 3: Create a personal rule

---
title: My Shortcuts
scope: personal
---
## VS Code shortcuts
 
- Cmd+Shift+L: Format document
- Cmd+Shift+U: Convert to uppercase

Step 4: Sync

aligntrue sync

Now your personal rules are:

• Pulled from your personal repo on every sync
• Available locally in .aligntrue/rules/
• Exported to your agents
• Pushed back to your personal repo

On another machine, just clone the project and run aligntrue sync—your personal rules sync automatically!

Troubleshooting

Rule still showing in git status after marking gitignore

Run sync again to update .gitignore:

aligntrue sync
git status

If still showing, manually remove from git cache:

git rm --cached .aligntrue/rules/rulename.md
git status  # Should now be gitignored

Personal-scope rules still in lockfile

Make sure scope: personal is in the rule’s frontmatter:

---
title: My Rule
scope: personal
---

Then sync and verify:

aligntrue sync
cat .aligntrue/lock.json | grep rulename  # Should NOT appear

Rules not syncing to remotes

Check your configuration:

1. Is remotes configured?
2. Do your rules have the correct scope?
3. Is the remote URL accessible? Try: git ls-remote <url>
4. Check for conflicts: same URL as a source? (not allowed)

Run verbose sync to see details:

aligntrue sync --verbose

Related

• Team Mode - How approval scopes work in team workflows
• Working with external sources - Adding and customizing external rules
• Personal Repository Setup - SSH and HTTPS configuration
• Source and remote issues - Resolving connection issues