matt/ai-ops-templates
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add sync protocol for portable context management

Browse source 
- ai-sync-protocol.md: Session start and post-change sync rules
- _sync section in schema for auto-sync configuration
- Updated client skill template with Forgejo fetch patterns
- Client projects now self-sufficient via central repo fetch

Version 1.1.0

Made-with: Cursor
This commit is contained in:
DMleadgen 2026-03-06 16:24:57 -07:00
parent 3cb8d3cb3f
commit 2598e55a54
5 changed files with 353 additions and 93 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

204
.cursor/rules/ai-sync-protocol.md Normal file
View file

@ -0,0 +1,204 @@
# 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.*

18
context/CHANGELOG.md
View file

@ -24,6 +24,24 @@ This file tracks all changes to the ai-ops-templates repository. Updates are log
---
## [2026-03-06] - Version 1.1.0
### Added
- `ai-sync-protocol.md` - Session start and post-change sync protocol
- `_sync` section in `ai-context.schema.json` for auto-sync configuration
- Forgejo fetch patterns in client skill template
### Changed
- Updated `client-skill.template.md` with central repository fetch instructions
- Session now starts with sync check from Forgejo
### Architecture
- Central management from Abundance project
- Single source of truth: Forgejo repo
- Client projects self-sufficient via fetch from Forgejo
---
## [2026-03-06] - Version 1.0.0
### Added

18
context/last-sync.json
View file

@ -1,13 +1,13 @@
{
"_meta": {
"last_updated": "2026-03-06T15:52:00Z",
"version": "1.0.0",
"last_updated": "2026-03-06T16:30:00Z",
"version": "1.1.0",
"description": "Timestamp tracking for context synchronization"
},
"last_sync": "2026-03-06T15:52:00Z",
"repository_url": "https://git.abundancepartners.app/abundance/ai-ops-templates",
"last_sync": "2026-03-06T16:30:00Z",
"repository_url": "https://git.abundancepartners.app/matt/ai-ops-templates",
"branch": "main",
"commit_hash": "initial",
"commit_hash": "v1.1.0",
"files": {
"templates": {
"schema-product.json": "2026-03-06T15:52:00Z",
@ -20,7 +20,8 @@
"ui-fixes.json": "2026-03-06T15:52:00Z",
"seo-rules.md": "2026-03-06T15:52:00Z",
"common-fixes.md": "2026-03-06T15:52:00Z",
"ai-decision-guide.md": "2026-03-06T15:52:00Z"
"ai-decision-guide.md": "2026-03-06T15:52:00Z",
"ai-sync-protocol.md": "2026-03-06T16:30:00Z"
},
"snippets": {
"add-internal-link.tsx": "2026-03-06T15:52:00Z",
@ -36,7 +37,10 @@
},
"schemas": {
"ai-cli.schema.json": "2026-03-06T15:52:00Z",
"ai-context.schema.json": "2026-03-06T15:52:00Z"
"ai-context.schema.json": "2026-03-06T16:30:00Z"
},
"skill-templates": {
"client-skill.template.md": "2026-03-06T16:30:00Z"
}
}
}

43
schemas/ai-context.schema.json
View file

@ -4,8 +4,49 @@
"title": "AI Context Manifest",
"description": "Schema for per-project AI context manifest - the single source of truth for AI agents",
"type": "object",
"required": ["client", "infrastructure"],
"required": ["client", "_sync"],
"properties": {
"_sync": {
"type": "object",
"description": "Sync configuration for fetching context from central repository",
"required": ["templates_repo"],
"properties": {
"templates_repo": {
"type": "string",
"format": "uri",
"description": "URL of the ai-ops-templates repository"
},
"last_check": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 timestamp of last sync check"
},
"auto_sync": {
"type": "boolean",
"default": true,
"description": "Whether to automatically sync at session start"
},
"sync_interval_hours": {
"type": "integer",
"default": 24,
"minimum": 1,
"description": "Hours between automatic sync checks"
},
"preset_path": {
"type": "string",
"description": "Path to preset file (e.g., presets/slc-bride.json)"
},
"cached_context": {
"type": "object",
"description": "Locally cached context from last sync",
"properties": {
"brand": { "type": "object" },
"rules": { "type": "array", "items": { "type": "string" } },
"snippets": { "type": "array", "items": { "type": "string" } }
}
}
}
},
"_meta": {
"type": "object",
"required": ["last_updated", "version"],

163
skill-templates/client-skill.template.md
View file

@ -1,11 +1,21 @@
---
name: {{CLIENT_NAME}}
description: Context and operations guide for {{CLIENT_NAME}} project. Use when working on {{DESCRIPTION}}.
description: Context and operations guide for {{CLIENT_NAME}}. Fetches brand, patterns, and infrastructure from central ai-ops-templates repository.
---
# {{CLIENT_NAME}}
{{PROJECT_DESCRIPTION}}
## Session Start Protocol
**CRITICAL: Before starting work, sync context from Forgejo:**
1. Read `.ai-context.json` in project root
2. Check `_sync.last_check` timestamp
3. If > 24 hours old or null, fetch fresh context:
- Brand preset: `https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/presets/{{CLIENT_SLUG}}.json`
- Common patterns: `https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/snippets/`
---
## Project Overview
@ -15,7 +25,23 @@ description: Context and operations guide for {{CLIENT_NAME}} project. Use when
| **Site URL** | {{SITE_URL}} |
| **Server** | {{SERVER_NAME}} ({{SERVER_IP}}) |
| **Database** | {{DATABASE_NAME}} |
| **Status** | {{PROJECT_STATUS}} |
| **Preset URL** | `.../presets/{{CLIENT_SLUG}}.json` |
---
## Context Sources (Forgejo)
All context is fetched from the central repository. Do NOT duplicate here.
| Resource | Forgejo URL |
|----------|-------------|
| Brand Preset | `.../raw/main/presets/{{CLIENT_SLUG}}.json` |
| UI Patterns | `.../raw/main/snippets/vendor-card.tsx` |
| Schema Templates | `.../raw/main/templates/schema-product.json` |
| SEO Rules | `.../raw/main/rules/seo-rules.md` |
| Decision Guide | `.../raw/main/rules/ai-decision-guide.md` |
**Base URL**: `https://git.abundancepartners.app/matt/ai-ops-templates`
---
@ -26,45 +52,39 @@ description: Context and operations guide for {{CLIENT_NAME}} project. Use when
# SSH into server
ssh root@{{SERVER_IP}}
# Or use abundance CLI
# Or use abundance CLI (if installed)
abundance srv ssh {{SERVER_NAME}}
```
### Coolify Deployment
- **Dashboard**: {{COOLIFY_URL}}
- **App ID**: {{COOLIFY_APP_ID}}
- **Deploy**: `abundance coolify deploy application {{COOLIFY_APP_ID}}`
- **Deploy via MCP**: `deploy_push({ target: "prod", app_id: "{{COOLIFY_APP_ID}}" })`
### Database
```bash
# Query database
abundance db query {{DATABASE_NAME}} "SELECT * FROM {{TABLE}} LIMIT 5"
# Create SSH tunnel
abundance db tunnel {{DATABASE_NAME}}
# Or use MCP
supabase_query({ query: "SELECT * FROM {{TABLE}} LIMIT $1", params: [5] })
```
---
## Brand Guidelines
## Brand Guidelines (Fetch from Forgejo)
### Colors
Brand colors, fonts, and styling are defined in:
```
https://git.abundancepartners.app/matt/ai-ops-templates/raw/main/presets/{{CLIENT_SLUG}}.json
```
**Quick Reference** (verify against preset):
| Color | Hex | Usage |
|-------|-----|-------|
| Primary | `{{PRIMARY_COLOR}}` | Buttons, links, highlights |
| Secondary | `{{SECONDARY_COLOR}}` | Accents, badges |
| Background | `{{BACKGROUND_COLOR}}` | Page background |
| Text | `{{TEXT_COLOR}}` | Body text |
### Typography
- **Headings**: {{HEADING_FONT}}
- **Body**: {{BODY_FONT}}
### Tailwind Config
Brand colors are defined in `presets/{{CLIENT_SLUG}}.json`. Reference via CSS variables:
```css
background-color: var(--primary);
```
---
@ -74,85 +94,49 @@ background-color: var(--primary);
|-------|-------------|-----------|
| {{ROUTE_1}} | {{ROUTE_1_DESC}} | `{{ROUTE_1_COMPONENT}}` |
| {{ROUTE_2}} | {{ROUTE_2_DESC}} | `{{ROUTE_2_COMPONENT}}` |
| {{ROUTE_3}} | {{ROUTE_3_DESC}} | `{{ROUTE_3_COMPONENT}}` |
---
## Database Schema
## Common Patterns (Fetch from Forgejo)
### Key Tables
| Table | Description | Key Columns |
|-------|-------------|-------------|
| {{TABLE_1}} | {{TABLE_1_DESC}} | {{TABLE_1_COLS}} |
| {{TABLE_2}} | {{TABLE_2_DESC}} | {{TABLE_2_COLS}} |
Patterns are maintained centrally. Fetch as needed:
### Common Queries
```sql
-- {{QUERY_1_DESC}}
SELECT * FROM {{TABLE}} WHERE {{CONDITION}};
### Vendor Card
```
GET .../raw/main/snippets/vendor-card.tsx
```
### Breadcrumb with Schema
```
GET .../raw/main/snippets/breadcrumb.tsx
```
### Schema Injection
```
GET .../raw/main/snippets/schema-inject.ts
```
---
## APIs
## Post-Change Sync
### {{API_1_NAME}}
- **Base URL**: `{{API_1_URL}}`
- **Auth**: {{API_1_AUTH}}
- **Env Key**: `{{API_1_ENV_KEY}}`
After making changes that should be reusable:
1. Identify if change is client-specific or general pattern
2. If general, push to `ai-ops-templates` on Forgejo
3. Update `context/last-sync.json` with timestamp
4. Add entry to `context/CHANGELOG.md`
---
## Common Patterns
### {{PATTERN_1_NAME}}
```{{PATTERN_1_LANG}}
{{PATTERN_1_CODE}}
```
### {{PATTERN_2_NAME}}
```{{PATTERN_2_LANG}}
{{PATTERN_2_CODE}}
```
---
## Integrations
| Service | Purpose | Config Location |
|---------|---------|-----------------|
| {{SERVICE_1}} | {{SERVICE_1_PURPOSE}} | {{SERVICE_1_CONFIG}} |
| {{SERVICE_2}} | {{SERVICE_2_PURPOSE}} | {{SERVICE_2_CONFIG}} |
---
## Troubleshooting
### {{ISSUE_1}}
**Symptom**: {{ISSUE_1_SYMPTOM}}
**Solution**: {{ISSUE_1_SOLUTION}}
### {{ISSUE_2}}
**Symptom**: {{ISSUE_2_SYMPTOM}}
**Solution**: {{ISSUE_2_SOLUTION}}
---
## Recent Changes
| Date | Change | Notes |
|------|--------|-------|
| {{DATE_1}} | {{CHANGE_1}} | {{NOTES_1}} |
---
## Context Metadata (Auto-Updated)
## Context Metadata
| Field | Value |
|-------|-------|
| _last_updated | {{LAST_UPDATED}} |
| _version | {{VERSION}} |
| _synced_from | git.abundancepartners.app/abundance/ai-ops-templates |
| _sync_repo | `https://git.abundancepartners.app/matt/ai-ops-templates` |
| _preset | `presets/{{CLIENT_SLUG}}.json` |
---
@ -165,9 +149,18 @@ abundance srv status
# View logs
abundance docker logs {{SERVER_NAME}} {{CONTAINER}} -f --tail 100
# Deploy to staging
deploy_push({ target: "staging", app_id: "{{STAGING_APP_ID}}" })
# Deploy via MCP
deploy_push({ target: "prod", app_id: "{{COOLIFY_APP_ID}}" })
# Deploy to production
deploy_push({ target: "prod", app_id: "{{PROD_APP_ID}}" })
# Fetch fresh context
# Read .ai-context.json, then fetch preset from Forgejo
```
---
## Self-Healing
If context seems wrong:
1. Force refresh: Set `_sync.last_check` to null in `.ai-context.json`
2. Fetch fresh preset from Forgejo
3. Verify against `.../raw/main/presets/{{CLIENT_SLUG}}.json`