> ## 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.

# AGENTS.md maintenance guide

> When and how to keep per-directory AGENTS.md files accurate — what to update, when, and how to validate them against the codebase they scope.

**Version:** 1.0.1\
**Last Updated:** 2026-04-10\
**Purpose:** When and how to update `AGENTS.md` files (not the same as root [AGENTS.md](https://github.com/Encore-OS/encoreos/blob/development/AGENTS.md) pattern quick reference)

***

## 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

```bash theme={null}
# 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

If updating root 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

```bash theme={null}
# Run validation
npm run validate-agents

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

### Step 5: Commit

```bash theme={null}
# Pre-commit hooks will run validation
git add AGENTS.md
git commit -m "Update AGENTS.md: [description]"
```

***

## How to Structure Content

### File Size Targets

| File Type          | Target      | Current    | Status          |
| ------------------ | ----------- | ---------- | --------------- |
| Root AGENTS.md     | \<500 lines | 1,939      | ⚠️ **CRITICAL** |
| Platform AGENTS.md | \<300 lines | \~655      | ⚠️ **LARGE**    |
| Shared AGENTS.md   | \<150 lines | \~400      | ⚠️ **LARGE**    |
| Core AGENTS.md     | \<200 lines | 250-1,000+ | ⚠️ **VARIES**   |

### Structure Guidelines

**Root AGENTS.md:**

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

**Nested AGENTS.md:**

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

### Content Guidelines

**DO:**

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

**DON'T:**

* ❌ 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:**
   ```bash theme={null}
   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

```bash theme={null}
# 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

**✅ Pass:** No critical issues\
**⚠️ Warning:** Size approaching limit, minor issues\
**❌ Fail:** Size exceeds target, version mismatches, sync issues

***

## 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:**
   ```bash theme={null}
   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/`.

***

**Last Updated:** 2026-04-10
**Next Review:** 2026-07-10 (Quarterly)