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
```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`:
```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
```javascript
// 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
```typescript
// GET https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/snippets/vendor-card.tsx
export function VendorCard({ vendor }: VendorCardProps) { ... }
```

### Fetch a Rule
```markdown
// 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.*