ai-ops-templates/.cursor/rules/ai-sync-protocol.md

AI Context Sync Protocol

This rule defines how context is synchronized between the central ai-ops-templates repository and individual client projects.

---

Architecture Overview

Abundance Project (Central)
       │
       ▼ (push after changes)
   Forgejo Repo ──────────────────┐
       │                          │
       ▼ (pull at session start)  │
   Client Project A               │
   Client Project B ◄─────────────┘
   Client Project C

• Central Hub: Abundance project manages all skills, rules, and templates
• Single Source of Truth: https://git.abundancepartners.app/matt/ai-ops-templates
• Client Projects: Self-sufficient, fetch everything from Forgejo

---

MANDATORY: Session Start Protocol

When starting work in ANY project, follow this sequence:

Step 1: Check for .ai-context.json

// Read this file first if it exists
{
  "_sync": {
    "templates_repo": "https://git.abundancepartners.app/matt/ai-ops-templates",
    "last_check": "2026-03-06T16:00:00Z",
    "auto_sync": true
  }
}

Step 2: Determine if Sync Needed

Check if last_check is:

• Null or missing: MUST sync now
• > 24 hours old: SHOULD sync now
• < 24 hours old: Optional (use cached context)

Step 3: Fetch Fresh Context from Forgejo

Use these raw URLs to fetch context:

# Brand preset
https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/presets/{client}.json

# Templates
https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/templates/{template}.json

# Rules
https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/rules/{rule}.md

# Snippets
https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/snippets/{snippet}.tsx

Step 4: Update last_check Timestamp

After fetching, update .ai-context.json:

{
  "_sync": {
    "last_check": "<current ISO timestamp>"
  }
}

---

MANDATORY: Post-Change Sync Protocol

After making changes that affect shared context:

Step 1: Identify Change Type

Change Type	Action Required
Client-specific code	No sync needed
New reusable pattern	Sync to central
Brand/styling change	Update preset, sync
Bug fix with general solution	Add to common-fixes, sync
New component template	Add to snippets, sync

Step 2: Update Central Repository

If in the Abundance project:

1. Update the relevant file in ai-ops-templates/
2. Update context/last-sync.json timestamps
3. Add entry to context/CHANGELOG.md
4. Git commit and push to Forgejo

If in a client project:

1. Identify the change that should be shared
2. Push the change to Forgejo ai-ops-templates repo
3. Update context/last-sync.json

Step 3: Verify Sync

Confirm the change is visible at:

https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/{path}

---

Context File Locations

In Abundance Project (Central)

ai-ops-templates/
├── presets/{client}.json       # Brand colors, fonts, config
├── templates/{name}.json       # Schema.org templates
├── rules/{name}.md             # Development rules
├── snippets/{name}.tsx         # Reusable code
├── schemas/{name}.schema.json  # JSON schemas
└── context/
    ├── CHANGELOG.md            # Change history
    └── last-sync.json          # Timestamps

In Client Projects

.ai-context.json                # Pointer to Forgejo + client config
.cursor/skills/{client}/SKILL.md  # Client-specific skill

---

Fetching Context Examples

Fetch a Brand Preset

// GET https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/presets/slc-bride.json
{
  "brand": {
    "colors": { "primary": "#ec4899", ... },
    "fonts": { "heading": "Playfair Display", ... }
  }
}

Fetch a Snippet

// GET https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/snippets/vendor-card.tsx
export function VendorCard({ vendor }: VendorCardProps) { ... }

Fetch a Rule

// GET https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/rules/seo-rules.md
# SEO Rules
...

---

Error Handling

Cannot Reach Forgejo

1. Use cached context if last_check < 24 hours
2. Proceed with work, note that sync is pending
3. Retry sync at end of session

Context File Not Found

1. Check if file exists in central repo
2. If new client, use presets/default.json as base
3. Create client-specific preset in central repo

Merge Conflicts

1. Prefer central repo version for templates/rules
2. Keep client-specific overrides in local .ai-context.json
3. Document conflict resolution in CHANGELOG

---

Quick Reference

Action	Command/URL
Check if sync needed	Read .ai-context.json → check _sync.last_check
Fetch preset	GET .../raw/main/presets/{client}.json
Fetch template	GET .../raw/main/templates/{name}.json
Fetch snippet	GET .../raw/main/snippets/{name}.tsx
Push changes	git add . && git commit -m "..." && git push
Verify sync	Check raw URL in browser

---

Self-Healing Protocol

If context seems stale or incorrect:

1. Force refresh: Set _sync.last_check to null, restart session
2. Verify source: Check Forgejo repo directly in browser
3. Rebuild: Delete local context, fetch fresh from Forgejo
4. Report: Add issue to central repo if problem persists

---

This rule is managed centrally in the Abundance project and synced to client projects via the ai-ops-templates repository.