🤖 Universal Context Architecture

Stop "Context Drift" in Multi-Agent AI Teams

One source of truth for Cursor, Claude Code, GitHub Copilot, Gemini, Amazon Q, and 16+ AI coding assistants.

Quick Start · How It Works · Supported Tools · Customize

---

🤔 The Problem

We're in the era of Multi-Vendor AI Development. Your team might be using:

🖱️ Cursor

🤖 Claude Code

🐙 GitHub Copilot

💎 Gemini CLI

☁️ Amazon Q

➕ 13 more...

The catch? Every tool has its own config file. They all drift apart over time.

😵 Before: Chaos
┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│ .cursorrules│  │  CLAUDE.md  │  │  GEMINI.md  │  │ copilot.md  │
│   v1.2      │  │   v1.5      │  │   v1.0      │  │   v1.3      │
│  (outdated) │  │  (current)  │  │  (wrong)    │  │  (missing)  │
└─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘
      ↓                ↓                ↓                ↓
   Different        Different        Different        Different
   conventions      conventions      conventions      conventions

You end up with duplicated rules, conflicting instructions, and AI assistants that hallucinate different project conventions.

---

💡 The Solution

Governor & Consumer Pattern

Instead of maintaining 19 different config files, use a hub-and-spoke architecture:

✨ After: Harmony
                         ┌─────────────────────┐
                         │     AGENTS.md       │
                         │     (The Hub)       │
                         │  Single Source of   │
                         │      Truth          │
                         └──────────┬──────────┘
                                    │
           ┌────────────┬───────────┼───────────┬────────────┐
           │            │           │           │            │
           ▼            ▼           ▼           ▼            ▼
     .cursorrules  CLAUDE.md   GEMINI.md   copilot.md    19 more...
        │            │           │           │            │
        └────────────┴───────────┴───────────┴────────────┘
                                 │
                      "Read AGENTS.md first"

Every vendor-specific config contains just one instruction:

"System: Read /AGENTS.md before doing anything."

---

🗂️ Architecture

📁 Your Project
│
├── 🎯 AGENTS.md                      ← THE HUB: Entry point for all AI agents
│
├── 📂 .agent/
│   │
│   ├── 📚 skills/                ← KNOWLEDGE (Atomic, Reusable)
│   │   ├── git.md                   "Here are our Git commands"
│   │   ├── db.md                    "Here's how to run migrations"
│   │   ├── test.md                  "Here's how to run tests"
│   │   └── review-checklist.md      "Here's the PR checklist"
│   │
│   ├── 🔄 workflows/             ← PROCESSES (Step-by-step)
│   │   ├── feature-dev.md           Plan → Code → Test
│   │   ├── bug-fix.md               Reproduce → Fix → Verify
│   │   ├── deploy.md                Lint → Build → Ship
│   │   └── pr-review.md             Fetch → Review → Approve
│   │
│   └── 🎭 sub-agents/            ← PERSONAS (Specialized Roles)
│       ├── qa.md                    "I am the QA Engineer"
│       ├── devops.md                "I am the DevOps Engineer"
│       └── tech-lead.md             "I am the Tech Lead"
│
├── 📂 .specify/memory/           ← GOVERNANCE (The Law)
│   ├── constitution.md              Tech Stack & Rules
│   └── plan.md                      Current Tasks & Sprint
│
└── 📂 [Pointer Files]            ← REDIRECTORS (Thin Wrappers)
    ├── .cursorrules                 → "Read AGENTS.md"
    ├── CLAUDE.md                    → "Read AGENTS.md"
    ├── GEMINI.md                    → "Read AGENTS.md"
    └── ... (19 total)               → "Read AGENTS.md"

---

🚀 Quick Start

Step 1️⃣   Use This Template Click the button below to create your own copy:

Step 2️⃣   Define Your Constitution Edit .specify/memory/constitution.md: # Your Tech Stack Frontend: React 18 + TypeScript + Tailwind Backend: Node.js + Express + Prisma Database: PostgreSQL Cloud: AWS # Your Rules - TypeScript everywhere, no `any` - All functions must be documented - Tests required for new features

Step 3️⃣   Set Your Plan Edit .specify/memory/plan.md: ## Current Sprint: User Authentication ### In Progress - [ ] Implement OAuth2 flow - [ ] Add password reset ### Up Next - [ ] Two-factor authentication

Step 4️⃣   Start Coding Open your project in any AI-powered IDE. The AI will automatically: 📖 Read the pointer file (.cursorrules, CLAUDE.md, etc.) 🎯 Navigate to AGENTS.md 📜 Load your constitution and plan ✅ Follow your rules consistently

---

🔌 Supported AI Tools

IDE / CLI	Config File	Status
Cursor	.cursorrules	✅
Windsurf	.windsurfrules	✅
Roo Code / Cline	.clinerules	✅
GitHub Copilot	.github/copilot-instructions.md	✅
Claude Code	CLAUDE.md	✅
Gemini CLI	GEMINI.md	✅
Amazon Q	AMAZON_Q.md	✅
Auggie CLI	.auggie.md	✅
CodeBuddy	.codebuddy	✅
Qoder	.qoder/context.md	✅
OpenCode	.opencode	✅
Amp	.amp.md	✅
Kilo Code	.kilo	✅
Qwen Code	.qwen	✅
IBM Bob	.bob/config	✅
Jules	.jules	✅
SHAI	.shai	✅
Codex CLI	CODEX.md	✅
Goose	GOOSE.md	✅

---

🧠 How It Works

📚 Skills	🔄 Workflows	🎭 Sub-Agents	📜 Governance
Atomic knowledge modules Each skill is a reusable piece of domain knowledge. git.md ├─ Branch naming ├─ Commit format └─ PR process	Step-by-step processes Workflows chain skills into complete procedures. feature-dev.md ├─ Step 1: Plan ├─ Step 2: Code └─ Step 3: Test ↗️ └── test.md	Specialized personas Sub-agents are experts that use specific skills & workflows. qa.md ├─ Uses: test.md ├─ Uses: bug-fix.md └─ Focus: Quality	The source of truth Constitution = the law Plan = current state memory/ ├─ constitution.md │ └─ "Never ignore me" └─ plan.md └─ "Here's what we're doing"

---

✨ Before vs After

😵 Before	✨ After
❌ 19 config files to maintain ❌ Rules drift between tools ❌ Duplicated documentation ❌ AI invents conventions ❌ Context gets lost mid-task ❌ Team members get different AI behavior	✅ 1 hub file + thin pointers ✅ Consistent rules everywhere ✅ Single source of truth ✅ AI follows YOUR conventions ✅ Context is preserved ✅ Same AI behavior for everyone

---

🛠️ Customization

➕ Adding a New AI Tool

Create a new pointer file for any AI tool:

# [Tool Name] Configuration

> System: Read /AGENTS.md before doing anything.

---

## Instructions

Before performing any task, you MUST:

1. Read `AGENTS.md` — The central hub for all project context
2. Read `.specify/memory/constitution.md` — The rules and tech stack
3. Check `.specify/memory/plan.md` — Current tasks and priorities

---

*This file redirects [Tool Name] to the Universal Context Architecture.*

📚 Adding a New Skill

1. Create a file in .agent/skills/
2. Start with a tagline: > Here is how to [do X].
3. Add commands, conventions, examples
4. Reference it from relevant workflows

Example:

# Docker Skill

> Here is how to build and run containers.

## Commands

\`\`\`bash
docker build -t myapp .
docker run -p 3000:3000 myapp
\`\`\`

🔄 Adding a New Workflow

1. Create a file in .agent/workflows/
2. Define numbered steps
3. Reference skills with links
4. Keep it action-oriented

Example:

# Hotfix Workflow

> Step 1: Branch. Step 2: Fix. Step 3: Deploy.

## Step 1: Create Hotfix Branch

Reference: `.agent/skills/git.md`

\`\`\`bash
git checkout -b hotfix/critical-issue main
\`\`\`

## Step 2: Apply Fix
...

🎭 Adding a New Sub-Agent

1. Create a file in .agent/sub-agents/
2. Define the persona and role
3. List which skills and workflows it uses
4. Add specific instructions

Example:

# Security Engineer Sub-Agent

> I am the Security Engineer. I review code for vulnerabilities.

## My Skills
- `.agent/skills/review-checklist.md`

## My Focus
- OWASP Top 10
- Input validation
- Authentication flows

---

🌟 Star History

If this helps your team, consider giving it a ⭐

Built with ❤️ for the Multi-Agent AI Era

Stop context drift. Start shipping.

---

_{Inspired by Spec-Kit and the Governor & Consumer pattern}