🚀 dotAIslash

VERSA - Universal Rules for AI Agents

Vendor-neutral Extensible Repo Spec for Agents

One .ai/ folder, every runtime

15+ AI coding tools, a pile of formats, still no shared standard.

If your team mixes IDE agents, CLIs, and repo bots, you end up duplicating rules across multiple files. Switch tools? Rewrite configs. Vendor lock-in by format continues.

IDE and Editor Assistants:

• 🟣 Cursor → .cursor/rules/*.mdc files (MDC format, not .cursorrules anymore)
• 🔵 Windsurf → .windsurf/rules/*.md files (shifted from .windsurfrules in Wave 8)
• 🟢 GitHub Copilot → .github/copilot-instructions.md + now supports AGENTS.md
• 🟠 Sourcegraph Cody → VS Code settings.json + custom command JSON files
• 🟡 Continue.dev → ~/.continue/config.yaml (config.json deprecated)
• 🔵 Warp Terminal → YAML Launch Configurations + MCP server setup

CLI-First Agents:

• 🟣 OpenAI Codex CLI → ~/.codex/config.toml + supports AGENTS.md
• 🟢 Factory Droid → .droid.yaml + AGENTS.md for conventions
• 🔵 Gemini CLI → ~/.gemini/settings.json + GEMINI.md hierarchy
• 🟡 Aider → .aider.conf.yml (YAML)
• 🟠 OpenHands → config.toml with named LLM configs

Special Cases:

• 🟢 Claude Code → .claude/settings.json + CLAUDE.md for instructions
• 🟡 Cline (VS Code) → .clinerules file or .clinerules/ directory
• 🟠 Sweep AI → sweep.yaml in JetBrains projects
• 🔴 Tabnine → Admin console + IDE settings (no standard file)

The Impact:

A typical stack like Cursor + Copilot + Gemini CLI means maintaining three rule systems at once:

• .cursor/rules/*.mdc
• .github/copilot-instructions.md
• .gemini/settings.json

Plus tool-specific files like .windsurf/rules/*.md, .aider.conf.yml, CLAUDE.md, AGENTS.md, etc.

Result: Fragmented ecosystem. Switching tools still triggers complete rewrites.

your-project/
└── .ai/                      ← One folder
    ├── context.json          ← One standard
    ├── profiles/             ← Every runtime
    │   ├── cursor.json
    │   ├── windsurf.json
    │   └── claude.json
    ├── rules/
    │   └── style.md
    └── agents/
        └── code-reviewer.json

VERSA defines 8 canonical primitives for agent configuration:

mkdir .ai
cd .ai

{
  "version": "1.0",
  "rules": ["rules/style.md"],
  "context": ["src/**/*.ts"],
  "settings": {
    "model": "claude-sonnet-4"
  }
}

// .ai/profiles/cursor.json
{
  "version": "1.0",
  "merge": "deep",
  "settings": {
    "shortcuts": {
      "review": "agents/code-reviewer.json"
    }
  }
}

<!-- .ai/rules/style.md -->
ai:meta
  priority: high
  attach: always
---

# Code Style Guide

- TypeScript strict mode
- Functional components
- Max line length: 100

• 📖 Read the Spec - Full VERSA 1.0 specification
• 🚀 Quick Start Guide - Get started in 5 minutes
• 📚 Examples - Real-world configurations
• 🔧 CLI Documentation - Command reference
• 💬 Discussions - Ask questions, share ideas

We're building VERSA openly with the community!

• 💡 Share Ideas - Join discussions
• 🐛 Report Issues - Found a problem? Open an issue
• 📝 Improve Docs - Help others understand VERSA
• 🔧 Build Adapters - Support a new tool
• 📚 Create Examples - Share your .ai/ configs
• 🧪 Write Tests - Improve conformance suite

See individual repositories for contributing guidelines.

• ✅ Core specification
• ✅ Website launch
• ✅ JSON Schemas (v1.0.0)
• ✅ Reference CLI (v1.0.0)
• ✅ Adapters (v1.0.0)
• ✅ Examples (v1.0.0)
• ✅ Conformance suite (v1.0.0)

• 📦 npm packages
• 🔌 Community adapters
• 📚 Comprehensive examples
• 🎓 Integration tutorials

• 🤝 Tool partnerships
• 🌍 Multi-language support
• 🔐 Advanced security
• 🚀 Performance optimizations

Boring is Beautiful

Plain JSON and Markdown. No DSLs. No magic. Just simple, portable formats.

Convention over Configuration

Sensible defaults. Minimal required fields. Override only what you need.

Security by Default

Explicit permissions. Deny-first policies. Secrets never in code.

Legend: 🟢 Stable · 🟡 In Progress · 🔴 Planned