Skip to Content
04 ReferenceVendor bags

Vendor bags reference

Vendor bags preserve agent-specific metadata for lossless round-trips between AlignTrue and agent formats.

See it in action: Check out the multi-agent example  for vendor bag usage.

What are vendor bags?

Vendor bags are namespaced fields in the vendor property that store agent-specific metadata. They enable:

  • Lossless round-trips: Import from agent → edit → export to agent without losing metadata
  • Agent-specific hints: Different AI hints or priorities per agent
  • Format preservation: Keep agent-specific fields that don’t map to AlignTrue’s schema

Example:

rules:
  - id: typescript-strict
    summary: Use TypeScript strict mode
    severity: error
    guidance: Enable strict mode in tsconfig.json
    vendor:
      cursor:
        ai_hint: "Check tsconfig.json and suggest strict options"
        priority: high
      claude:
        mode: "assistant"

When to use vendor bags

Use vendor bags for

Agent-specific AI hints:

vendor:
  cursor:
    ai_hint: "Focus on TypeScript best practices"
  claude:
    context: "Emphasize code review perspective"

Agent-specific priorities or modes:

vendor:
  cursor:
    priority: high
    quick_fix: true
  copilot:
    suggestions: "detailed"

Metadata that doesn’t fit AlignTrue’s schema:

vendor:
  cursor:
    session: "dev-session-1"
    tags: ["experimental"]

Don’t use vendor bags for

Core rule logic - Use guidance field:

# Bad
vendor:
  cursor:
    rule_text: "Always use const instead of let"
 
# Good
guidance: |
  Always use const instead of let for immutable variables.

Severity levels - Use severity field:

# Bad
vendor:
  cursor:
    severity: "high"
 
# Good
severity: error

File patterns - Use applies_to:

# Bad
vendor:
  cursor:
    files: ["**/*.ts"]
 
# Good
applies_to:
  patterns: ["**/*.ts"]

Syntax

Basic syntax

rules:
  - id: example-rule
    summary: Example rule
    vendor:
      <agent-name>:
        <field>: <value>

Multiple agents

rules:
  - id: example-rule
    summary: Example rule
    vendor:
      cursor:
        ai_hint: "Cursor-specific hint"
      claude:
        mode: "assistant"
      copilot:
        suggestions: "conservative"

Nested fields

vendor:
  cursor:
    config:
      mode: "strict"
      options:
        - "check-types"
        - "check-syntax"

Examples

Example 1: Different AI hints per agent

Use case: Same rule, different hints for different agents.

rules:
  - id: require-tests
    summary: All features must have tests
    severity: error
    applies_to:
      patterns: ["src/**/*.ts"]
    guidance: |
      Write unit tests for all new features.
      Test files should be co-located with source files.
    vendor:
      cursor:
        ai_hint: "Suggest test file path and basic test structure using Vitest"
        quick_fix: true
      claude:
        mode: "reviewer"
        context: "Emphasize test coverage and edge cases"
      copilot:
        suggestions: "detailed"
        examples: true

Result:

  • All agents enforce the rule
  • Cursor gets quick fix suggestions
  • Claude focuses on review perspective
  • Copilot provides detailed examples

Example 2: Agent-specific priorities

Use case: Different priority levels per agent.

rules:
  - id: no-console-log
    summary: No console.log in production code
    severity: warn
    guidance: |
      Use proper logging library instead of console.log.
    vendor:
      cursor:
        priority: high # Show prominently in Cursor
        auto_fix: true
      claude:
        priority: medium # Less prominent in Claude
      copilot:
        priority: low # Background suggestion only

Result:

  • Cursor shows the rule prominently with auto-fix
  • Claude shows it with medium priority
  • Copilot suggests it in background

Example 3: Volatile fields

Use case: Exclude session IDs and timestamps from hashing.

rules:
  - id: example-rule
    summary: Example rule
    vendor:
      cursor:
        session_id: "abc123" # Changes frequently
        timestamp: "2025-01-15" # Changes on every sync
      _meta:
        volatile: ["cursor.session_id", "cursor.timestamp"]

Result:

  • Session ID and timestamp preserved during round-trips
  • But excluded from lockfile hashing
  • Prevents false drift detection

Volatile fields

Volatile fields are excluded from lockfile hashing to prevent false drift detection.

Marking fields as volatile

Use vendor._meta.volatile to specify patterns:

vendor:
  cursor:
    session_id: "abc123"
    timestamp: "2025-01-15"
    important_field: "keep-this"
  _meta:
    volatile: ["cursor.session_id", "cursor.timestamp"]

Pattern matching

Volatile supports wildcards:

vendor:
  _meta:
    volatile:
      - "cursor.session_id" # Exact match
      - "*.timestamp" # Any agent's timestamp
      - "cursor.temp_*" # Cursor fields starting with temp_

Common volatile fields

Session metadata:

volatile: ["*.session_id", "*.session_token"]

Timestamps:

volatile: ["*.timestamp", "*.last_modified", "*.created_at"]

Temporary data:

volatile: ["*.temp_*", "*.cache_*"]

Round-trip preservation

Vendor bags are preserved during:

Import from agent

aligntrue import cursor --write

Cursor-specific fields → vendor.cursor namespace

Export to agent

aligntrue sync

vendor.cursor namespace → Cursor-specific fields

Sync operations

aligntrue sync

All vendor bags preserved in IR and agent files.

What’s preserved

Preserved:

  • All fields in vendor.<agent> namespace
  • Nested objects and arrays
  • Custom metadata

Not preserved:

  • Fields outside vendor namespace
  • Fields marked as volatile (excluded from hashing only)

Agent-specific fields

Common vendor bag fields by agent.

Cursor

vendor:
  cursor:
    ai_hint: string          # Hint for AI
    priority: "high" | "medium" | "low"
    quick_fix: boolean       # Enable quick fix
    session: string          # Session metadata
    tags: string[]           # Custom tags

Example:

vendor:
  cursor:
    ai_hint: "Focus on TypeScript best practices"
    priority: high
    quick_fix: true

Claude

vendor:
  claude:
    mode: "assistant" | "reviewer" | "pair"
    context: string          # Context hint
    examples: boolean        # Include examples

Example:

vendor:
  claude:
    mode: "reviewer"
    context: "Emphasize code quality and maintainability"

Copilot

vendor:
  copilot:
    suggestions: "conservative" | "balanced" | "detailed"
    examples: boolean        # Include examples
    priority: "high" | "medium" | "low"

Example:

vendor:
  copilot:
    suggestions: "detailed"
    examples: true

AGENTS.md (universal format)

vendor:
  agents_md:
    original_severity: string # Original severity label
    section: string # Section heading

Example:

vendor:
  agents_md:
    original_severity: "ERROR"
    section: "Code Quality"

Other agents

For complete list of agent-specific fields, see:

Best practices

1. Use vendor bags sparingly

Only use vendor bags for truly agent-specific settings.

Why: Too many vendor bags make rules hard to maintain.

2. Keep core logic in guidance

Put rule logic in guidance, not vendor bags.

Why: Guidance is universal and works across all agents.

3. Document vendor bag usage

Add comments explaining why vendor bags are needed.

rules:
  - id: example
    summary: Example
    # Cursor needs quick fix, Claude needs review context
    vendor:
      cursor:
        quick_fix: true
      claude:
        mode: "reviewer"

4. Mark volatile fields

Exclude session IDs and timestamps from hashing.

vendor:
  _meta:
    volatile: ["*.session_id", "*.timestamp"]

Why: Prevents false drift detection.

5. Test round-trips

Verify vendor bags are preserved:

# Import
aligntrue import cursor --write
 
# Export
aligntrue sync
 
# Check preserved
diff .cursor/rules/original.mdc .cursor/rules/aligntrue.mdc

Troubleshooting

Vendor bags not preserved

Problem: Agent-specific fields lost after sync.

Check:

  1. Verify vendor namespace:
# Bad
cursor:
  ai_hint: "hint"
 
# Good
vendor:
  cursor:
    ai_hint: "hint"
  1. Check exporter supports vendor bags:
aligntrue adapters list | grep cursor

Lockfile always changes

Problem: Lockfile hash changes even though rules didn’t change.

Cause: Non-volatile fields changing (timestamps, session IDs).

Fix: Mark fields as volatile:

vendor:
  _meta:
    volatile: ["cursor.session_id", "*.timestamp"]

Different behavior across agents

Problem: Agents behave differently despite same vendor bags.

Expected: Agents interpret vendor bags differently. Vendor bags are hints, not guarantees.

Check fidelity notes:

tail -20 .cursor/rules/aligntrue.mdc

Summary

Vendor bags enable:

  • ✅ Lossless round-trips between AlignTrue and agents
  • ✅ Agent-specific hints and priorities
  • ✅ Metadata preservation

Use vendor bags for:

  • ✅ Agent-specific AI hints
  • ✅ Agent-specific priorities or modes
  • ✅ Metadata that doesn’t fit AlignTrue’s schema

Don’t use vendor bags for:

  • ❌ Core rule logic (use guidance)
  • ❌ Severity levels (use severity)
  • ❌ File patterns (use applies_to)

Key takeaway: Vendor bags are powerful but should be used sparingly. Keep core rules consistent, use vendor bags only for truly agent-specific settings.

Last updated on
Markdown authoring guideYAML library design