AGENTS.md maintenance guide

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

​

When to Update AGENTS.md

​

Immediate Updates (Do Now)

• ✅ Core rules or patterns change
• ✅ Architecture boundaries change
• ✅ Security requirements change
• ✅ Version numbers change (update all references)

​

Regular Updates

• Monthly: Quick version reference check
• Quarterly: Comprehensive review and optimization
• Weekly: During regular documentation review

​

How to Update AGENTS.md

​

Step 1: Check Current State

# Run validation script
npm run validate-agents

# Review report
cat reports/agents-validation.md

​

Step 2: Make Changes

1. Update Content:
   • Follow structure guidelines
   • Keep size targets in mind
   • Use examples (good vs bad patterns)
   • Link to detailed docs instead of duplicating
2. Update Version:
   • Root AGENTS.md: Update version if significant changes
   • Nested files: Update root version reference
3. Update Dates:
   • Update “Last Updated” date
   • Add to changelog if significant

​

Step 3: Sync to AGENTS.md

1. Update Core Content:
   • Copy essential rule changes
   • Adapt tool-specific context
   • Update version references
2. Verify Sync:
   • Run validation script
   • Check sync status in report
   • Fix any issues

​

Step 4: Validate

# Run validation
npm run validate-agents

# Check for:
# - Size compliance
# - Version references
# - Sync status
# - Structure issues

​

Step 5: Commit

# Pre-commit hooks will run validation
git add AGENTS.md
git commit -m "Update AGENTS.md: [description]"

​

How to Structure Content

​

File Size Targets

​

Structure Guidelines

1. Quick Reference (Start Here)
2. Quick Start Workflow
3. Document Map
4. Common Mistakes
5. Decision Trees
6. Architecture Rules (summary, link to details)
7. Code Standards (summary, link to details)
8. Patterns (summary, link to Pattern Library)
9. Pre-Flight Checklist
10. Key References

1. Module Overview
2. Module-Specific Patterns
3. Key References (to root, platform, specs)

​

Content Guidelines

• ✅ Use examples (good vs bad)
• ✅ Link to detailed docs
• ✅ Keep concise
• ✅ Be actionable
• ✅ Reference root version

• ❌ Duplicate root content
• ❌ Include own version (nested files)
• ❌ Exceed size targets
• ❌ Use vague rules
• ❌ Forget to sync with AGENTS.md

​

Sync Process Quick Steps

​

When Updating Root AGENTS.md

1. Make Changes to AGENTS.md
2. Update Version if significant changes
3. Sync to AGENTS.md:
   • Update core content
   • Fix version references
   • Update sync status
4. Run Validation:
   npm run validate-agents
   
5. Fix Issues reported by validation
6. Commit both files together

​

Version Reference Checklist

• AGENTS.md version matches AI_GUIDE.md reference
• No active guidance refers to deleted LOVABLE_KNOWLEDGE.md; references should point to AGENTS.md
• AI_GUIDE.md version matches in both files
• constitution.md version matches in both files

​

Validation Commands

​

Basic Validation

# Run validation script
npm run validate-agents

# With custom output path
npm run validate-agents --output reports/custom-report.md

​

What Validation Checks

• ✅ File size compliance
• ✅ Version references
• ✅ Section structure
• ✅ Sync status (AGENTS.md vs AGENTS.md)
• ✅ Potential conflicts
• ✅ Required sections

​

Interpreting Results

​

Common Tasks

​

Adding a New Pattern

1. Check Size: Will addition exceed target?
2. Choose Location:
   • Root AGENTS.md: Platform-wide patterns
   • Platform AGENTS.md: PF-specific patterns
   • Core AGENTS.md: Module-specific patterns
3. Add Pattern:
   • Include good vs bad examples
   • Link to detailed docs if needed
   • Update quick reference table
4. Sync: If in root, update AGENTS.md
5. Validate: Run validation script

​

Fixing Version References

1. Identify Mismatches:
   npm run validate-agents
   
2. Update References:
   • Platform AGENTS.md: Ensure the **Version:** header matches the current entry for src/platform/AGENTS.md in docs/VERSIONS.md.
   • Root AGENTS.md: Ensure all cross-references to AGENTS.md, AI_GUIDE.md, and any core-specific AGENTS.md files use the versions listed in docs/VERSIONS.md.
   • Archived/Legacy docs: If you must touch archived docs (e.g., under docs/archive/ai-docs/), keep their internal version references self-consistent, but do not bump versions unless explicitly required.
3. Validate: Run validation script again

​

Optimizing File Size

1. Identify Large Sections:
   • Pattern Library (~400 lines)
   • MCP Usage (~150 lines)
   • Detailed standards (~150 lines)
2. Move to Separate Files:
   • Pattern index → .cursor/rules/quick-reference.mdc and .cursor/rules/pattern-decision-tree.md
   • Quick Reference → .cursor/rules/quick-reference.mdc
   • MCP Usage → docs/development/MCP_USAGE.md
   • Standards → Link to existing docs
3. Update AGENTS.md:
   • Keep summary
   • Add links to moved content
   • Update quick reference
4. Validate: Verify size compliance

​

Size Optimization Strategies

​

If Root AGENTS.md >500 Lines

1. Split Pattern Library (~400 lines)
2. Move MCP Usage (~150 lines)
3. Link to Detailed Docs (~150 lines)
4. Use .cursor/rules for complex, scoped rules

​

If Core AGENTS.md >200 Lines

1. Link to Spec Docs instead of including full patterns
2. Centralize Common Content (e.g., PF adoption status)
3. Keep Only Critical Patterns inline

​

Related Documentation

• Unified Quick Reference: AGENTS.md (includes Lovable-specific content)
• Cursor Best Practices: docs/development/AGENTS_BEST_PRACTICES_CURSOR.md
• Documentation Standards: docs/DOCUMENTATION_STANDARDS.md

Note: LOVABLE_KNOWLEDGE.md was consolidated into AGENTS.md as of 2026-01-25. Previous sync/comparison docs are archived in docs/archive/ai-docs/.