diff --git a/.cursor/rules/ai-sync-protocol.md b/.cursor/rules/ai-sync-protocol.md new file mode 100644 index 0000000..3c60c4e --- /dev/null +++ b/.cursor/rules/ai-sync-protocol.md @@ -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": "" + } +} +``` + +--- + +## 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.* diff --git a/context/CHANGELOG.md b/context/CHANGELOG.md index d26d562..3e3b0da 100644 --- a/context/CHANGELOG.md +++ b/context/CHANGELOG.md @@ -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 diff --git a/context/last-sync.json b/context/last-sync.json index c2488a4..c6818ee 100644 --- a/context/last-sync.json +++ b/context/last-sync.json @@ -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" } } } diff --git a/schemas/ai-context.schema.json b/schemas/ai-context.schema.json index 4dea64a..e528d50 100644 --- a/schemas/ai-context.schema.json +++ b/schemas/ai-context.schema.json @@ -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"], diff --git a/skill-templates/client-skill.template.md b/skill-templates/client-skill.template.md index a70ffe1..d094740 100644 --- a/skill-templates/client-skill.template.md +++ b/skill-templates/client-skill.template.md @@ -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`