Skip to Content
GuidesSolo developer guide

Solo developer guide

This guide shows how solo developers use AlignTrue to maintain consistent AI agent behavior across personal projects without team overhead.

Quick setup (60 seconds)

Install CLI:

bash npm install -g aligntrue

Initialize project:

cd my-project
aligntrue init
 
# Sync to agents
aligntrue sync

Result: Rules synced to Cursor and AGENTS.md. Start coding with consistent agent behavior. Edit .aligntrue/rules/*.md as the source; exports are read-only.

Organizing your rules

As your project grows, you may want to organize rules differently:

Single file (getting started)

Best for: Solo developers, < 20 rules, getting started

Store all rules in one file under .aligntrue/rules/ (source of truth):

project/
├── .aligntrue/
│   ├── config.yaml
│   └── rules/
│       └── project-rules.md  ← Edit here
└── AGENTS.md                 ← Export (read-only)

Setup:

aligntrue init
aligntrue sync

Everything is simple and fast. .aligntrue/rules/ stays the source of truth (auto-generated from init), and AGENTS.md/.cursor exports are read-only outputs.

Multi-file (when AGENTS.md grows large)

Best for: Projects with 20+ rules, easier navigation

Split rules into multiple files in .aligntrue/rules/:

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

Migration:

# Split your AGENTS.md into multiple files
aligntrue sources split --yes
 
# Sync
aligntrue sync

Benefits:

  • Logical organization by concern
  • Reduced merge conflicts if using git
  • Easier to find and update specific rules

Monorepo scopes (multiple stacks)

Best for: Monorepos with frontend/backend/services

Use scopes to apply different rules to different directories:

# .aligntrue/config.yaml
sources:
  - type: local
    path: .aligntrue/rules
 
scopes:
  - path: "apps/web"
    inherit: true # Includes root rules
  - path: "services/api"
    inherit: true

Each scope can have its own AGENTS.md or .cursor/rules/ with inherited rules.

When to use: Multiple projects in one repo that need context-specific rules.

Solo mode features

What you get:

  • Local-first operation (no required network calls)
  • Lockfile disabled by default (no drift detection overhead)
  • Bundle disabled by default (no dependency merging)
  • Fast iteration
  • Full customization (plugs, overlays, scopes)

What you don’t need:

  • Team mode (enable with aligntrue team enable if needed)
  • Lockfile validation (enable if you want reproducibility)

Daily workflow scenarios

Scenario 1: Starting a new project

Goal: Set up AlignTrue with sensible defaults in under 60 seconds.

Steps:

# 1. Initialize project
cd my-new-project
aligntrue init
 
# Interactive prompts:
# - Project name: my-new-project
# - Primary agent: cursor
# - Include base-global align? yes
# - Include stack align? nextjs (or your stack)
 
# 2. Sync to agents
aligntrue sync
 
# 3. Start coding
cursor .

What happened:

  • Created .aligntrue/rules (internal IR, auto-generated)
  • Created or detected your agent files (.cursor/rules/*.mdc, AGENTS.md, etc.)
  • Pulled example Aligns from local examples
  • Exported to all detected agent formats
  • Ready to sync rules to all agents

Next steps:

  • Customize test command: aligntrue plugs set test.cmd "pnpm test"
  • Adjust severity: aligntrue override add --selector 'rule[id=...]' --set severity=warn

Scenario 2: Using example Aligns

Goal: Use example Aligns from the AlignTrue repository and customize for your project.

Steps:

# 1. Browse examples
# Check examples/aligns/ directory
 
# 2. Import align via git source
# Add to .aligntrue/config.yaml:
# sources:
#   - type: git
#     url: https://github.com/AlignTrue/aligntrue
#     path: examples/aligns/testing.yaml
 
# 3. Sync rules to all agents
aligntrue sync
 
# 3. Audit plugs (see what needs customization)
aligntrue plugs list
 
# Output:
# Slots declared:
#   test.cmd
#     Required: true
#     Status: ⚠ required
#     Example: pytest -q
 
# 4. Set required plugs
aligntrue plugs set test.cmd "pnpm test"
 
# 5. Sync with filled plugs
aligntrue sync

Customization options:

Plugs (stack-specific values):

aligntrue plugs set test.cmd "pnpm test"
aligntrue plugs set docs.url "https://docs.myproject.com"

Overlays (severity adjustments):

aligntrue override add \
  --selector 'rule[id=no-console-log]' \
  --set severity=warn  # Downgrade from error

Result: Example align customized for your project without forking.

Scenario 3: Sharing rules across personal projects

Goal: Maintain consistent rules across multiple personal projects.

Option A: Git source (recommended for personal standards)

# 1. Create personal standards repo
mkdir my-standards
cd my-standards
git init
 
# 2. Create rules as markdown files
mkdir -p rules
cat > rules/coding-standards.md <<EOF
---
title: My Custom Coding Standard
---
 
# My custom coding standard
 
Always do X because Y. This rule applies to all TypeScript files.
 
## Guidelines
 
- Prefer explicit types over any
- Use meaningful variable names
- Add comments for complex logic
EOF
 
# 3. Commit and push
git add rules/
git commit -m "Initial standards"
git remote add origin https://github.com/you/my-standards
git push -u origin main
 
# 4. Use in projects
cd ~/projects/project-a
aligntrue init
 
# Add to .aligntrue/config.yaml:
sources:
  - type: git
    url: https://github.com/you/my-standards
    ref: main
    path: rules
 
aligntrue sync

Option B: Local align (quick iteration)

# 1. Create local rules directory
mkdir -p ~/.aligntrue/rules
 
cat > ~/.aligntrue/rules/my-standards.md <<EOF
---
title: My Custom Coding Standard
---
 
# My custom coding standard
 
Always do X because Y.
EOF
 
# 2. Copy to projects
cp ~/.aligntrue/rules/my-standards.md ~/projects/project-a/.aligntrue/rules/
 
# 3. Sync
cd ~/projects/project-a
aligntrue sync

Result: Consistent rules across all personal projects.

Scenario 4: Customizing third-party Aligns

Goal: Use community align but adjust for personal preferences.

Steps:

# 1. Pull third-party align
# .aligntrue/rules:
sources:
  - type: git
    url: https://github.com/community/typescript-standards
    ref: v1.0.0
 
# 2. Sync to see what you get
aligntrue sync
 
# 3. Adjust severity for personal preference
aligntrue override add \
  --selector 'rule[id=strict-null-checks]' \
  --set severity=warn  # Too strict for personal projects
 
# 4. Customize test command
aligntrue plugs set test.cmd "pnpm test"
 
# 5. Sync with customizations
aligntrue sync

Result: Community align customized without forking.

Scenario 5: Managing multiple stacks (monorepo)

Goal: Different rules for frontend vs backend in personal monorepo.

Structure:

my-monorepo/
├── apps/
│   └── web/          # Next.js
└── packages/
    └── api/          # Node.js

Configuration:

# .aligntrue/config.yaml
sources:
  - type: git
    url: https://github.com/org/base-rules
    ref: v1.0.0
  - type: git
    url: https://github.com/org/nextjs-rules
    ref: v1.0.0
  - type: git
    url: https://github.com/org/node-rules
    ref: v1.0.0
 
scopes:
  - path: "apps/web"
    include: ["**/*.ts", "**/*.tsx"]
    rulesets: ["base-rules", "nextjs-rules"]
 
  - path: "packages/api"
    include: ["**/*.ts"]
    rulesets: ["base-rules", "node-rules"]
 
plugs:
  fills:
    test.cmd: "pnpm test"

Workflow:

# 1. Set up scopes in config
# (edit .aligntrue/config.yaml as above)
 
# 2. Sync
aligntrue sync
 
# 3. Verify scopes
aligntrue scopes
 
# Output:
# apps/web: base-rules, nextjs-rules
# packages/api: base-rules, node-rules

Result: Each directory gets appropriate stack-specific rules.

Customization patterns

When to use plugs

Use plugs for:

  • Test commands that vary by stack
  • File paths specific to your project
  • URLs, author names, project metadata

Example:

# Set test command
aligntrue plugs set test.cmd "pnpm test"
 
# Set author name
aligntrue plugs set author.name "Your Name"
 
# Set docs URL
aligntrue plugs set docs.url "https://docs.yourproject.com"

When to use overlays

Use overlays for:

  • Adjusting severity for personal preference
  • Temporarily disabling strict rules during refactoring
  • Customizing third-party Aligns without forking

Example:

# Downgrade severity during refactoring
aligntrue override add \
  --selector 'rule[id=strict-null-checks]' \
  --set severity=warn
 
# Disable autofix that conflicts with your workflow
aligntrue override add \
  --selector 'rule[id=prefer-const]' \
  --remove autofix

When to use scopes

Use scopes for:

  • Monorepos with multiple stacks
  • Different rules for new vs legacy code
  • Progressive adoption of stricter rules

Example:

scopes:
  # Strict rules for new code
  - path: "src/new"
    rulesets: ["typescript-strict"]
 
  # Lenient rules for legacy code
  - path: "src/legacy"
    rulesets: ["typescript-lenient"]

Tips and best practices

Keep rules simple and focused

Good:

rules:
  - id: test-before-commit
    summary: Run tests before committing
    guidance: Run [[plug:test.cmd]] before committing
    applies_to: ["**/*.ts"]

Bad:

rules:
  - id: complex-rule
    summary: Do many things
    guidance: |
      Step 1: Do X
      Step 2: Do Y
      Step 3: Do Z
      Step 4: Do A
      # ... 50 more steps

Why: Simple rules are easier to understand and maintain.

Backup before major changes

# Create a manual backup (includes agent exports)
aligntrue backup create --notes "before-major-refactor"
 
# Make changes
# ... edit rules, add overlays, etc ...
 
# If something breaks, restore
aligntrue backup restore --timestamp <backup-id>

Document your decisions

Use YAML comments to explain customizations:

overlays:
  overrides:
    # Personal preference: Warnings instead of errors during development
    # Will upgrade to error once codebase is clean
    - selector: "rule[id=strict-null-checks]"
      set:
        severity: "warn"
 
plugs:
  fills:
    # Using pnpm for all personal projects
    test.cmd: "pnpm test"

Version control your rules

# Add to git
git add .aligntrue/
git commit -m "chore: Add AlignTrue rules"
 
# .gitignore (optional)
.aligntrue/.cache/        # Cache directory
.aligntrue/privacy-consent.json  # Per-machine consent

What to commit:

  • .aligntrue/rules - Source of truth (edit here)
  • .aligntrue/config.yaml - Configuration settings
  • AGENTS.md - Exported rules for agents (read-only, optional to track)
  • .cursor/rules/ - Exported Cursor rules (read-only, optional)

What NOT to commit:

  • .aligntrue/.cache/ - Cache directory
  • .aligntrue/privacy-consent.json - Per-machine consent
  • .aligntrue/lock.json - Only present in team mode

Common pitfalls and solutions

Pitfall 1: Unresolved required plugs

Problem: Sync fails with “Unresolved required plugs”

Solution:

# 1. Audit plugs
aligntrue plugs list
 
# 2. Set missing plugs
aligntrue plugs set test.cmd "pnpm test"
 
# 3. Sync again
aligntrue sync

Pitfall 2: Too many overlays

Problem: Maintaining many overlays becomes tedious

Solution: Fork the align or create your own:

# Instead of 20 overlays, create your own rules
mkdir -p .aligntrue/rules
 
cat > .aligntrue/rules/my-custom.md <<EOF
---
title: My Custom Rules
---
 
# My custom rules
 
Your customized rules here.
EOF
 
# Rules in .aligntrue/rules/ are automatically used
aligntrue sync

Pitfall 3: Forgetting to sync after changes

Problem: Rules changed but agents not updated

Solution: Always sync after changes:

# After editing rules
aligntrue sync
 
# After setting plugs
aligntrue plugs set test.cmd "pnpm test"
aligntrue sync
 
# After adding overlays
aligntrue override add --selector '...' --set severity=warn
aligntrue sync

Tip: Create an alias:

# ~/.bashrc or ~/.zshrc
alias async='aligntrue sync'

Pitfall 4: Not using version control

Problem: Lost rules after system crash or accidental deletion

Solution: Commit rules to git:

git add .aligntrue/
git commit -m "chore: Update AlignTrue rules"

Pitfall 5: Overcomplicating setup

Problem: Spending too much time configuring instead of coding

Solution: Start simple:

# Minimal setup (60 seconds)
aligntrue init
aligntrue sync
 
# Add customizations incrementally as needed
# Don't try to perfect everything upfront

Workflow examples

Example 1: Quick project setup

# 1. Create project
mkdir my-app && cd my-app
git init
 
# 2. Initialize AlignTrue
aligntrue init
# Select: cursor, base-global, nextjs
 
# 3. Set test command
aligntrue plugs set test.cmd "pnpm test"
 
# 4. Sync
aligntrue sync
 
# 5. Start coding
cursor .

Time: 60 seconds

Example 2: Experiment with rules

# 1. Create backup
aligntrue backup create --notes "before-experiment"
 
# 2. Try different severity
aligntrue override add \
  --selector 'rule[id=no-console-log]' \
  --set severity=off
 
# 3. Sync and test
aligntrue sync
# ... code and see how it feels ...
 
# 4. If you don't like it, restore
aligntrue backup restore --timestamp <backup-id>

Example 3: Share rules with friend

# 1. Push rules to GitHub
git add .aligntrue/
git commit -m "Add AlignTrue rules"
git push
 
# 2. Friend clones and syncs
git clone https://github.com/you/my-project
cd my-project
aligntrue sync
 
# 3. Friend gets same rules

Upgrading to team mode (optional)

If you start collaborating, upgrade to team mode:

# Enable team mode
aligntrue team enable
 
# Creates:
# - .aligntrue/lock.json (lockfile for reproducibility)
 
# Commit team files
git add .aligntrue/lock.json
git commit -m "Enable AlignTrue team mode"

See Team Guide for team collaboration workflows.

Summary

Solo developer workflow:

  1. Quick setup - aligntrue init (auto-sync, 60 seconds)
  2. Customize - Use plugs, overlays, and scopes as needed
  3. Iterate fast - No team overhead
  4. Version control - Commit rules to git
  5. Share easily - Git source or local Aligns

Key principles:

  • Start simple, add complexity only when needed
  • Use example Aligns as starting point
  • Customize with plugs, overlays, and scopes
  • Document decisions with comments
  • Version control your rules

Next steps:

Last updated on
GuidesTeam guide