One .ai/ folder, every runtime
VERSA is the canonical specification for portable agent configuration. It defines a standard .ai/ folder structure that works across Cursor, Windsurf, Claude, Aider, and any future AI coding tool.
Every AI coding tool has its own config format:
- 🔴 Cursor uses
.cursorrulesand workspace settings - 🔵 Windsurf has its own configuration
- 🟢 Claude projects have different structures
- 🟡 Aider uses
.aider.conf.yml
Result: Your project context is fragmented and tool-specific.
your-project/
└── .ai/
├── context.json # Base configuration
├── profiles/
│ ├── cursor.json # Cursor-specific overrides
│ ├── windsurf.json # Windsurf-specific overrides
│ └── claude.json # Claude-specific overrides
├── rules/
│ ├── style.md # Code style guidelines
│ └── security.md # Security policies
├── agents/
│ └── code-reviewer.json
└── tools/
└── mcp-servers.json
One folder. Every runtime. Portable forever.
|
Write once, run anywhere. Your Explicit permission model: deny → ask → allow. Secret bindings and redaction built-in. |
Plain JSON and Markdown. Human-readable. Git-friendly. Easy to diff and review. 8 canonical primitives: Rules, Prompts, Agents, Memory, Knowledge, Tools, Settings, Permissions. |
| Category | Purpose | Example |
|---|---|---|
| 📜 Rules | Persistent project context | Code style, architecture patterns |
| 💬 Prompts | Reusable templates with variables | Bug report template, feature spec |
| 🤖 Agents | Declarative agent configurations | Code reviewer, documentation writer |
| 🧠 Memory | Retention policies and notes | Session memory, project knowledge |
| 📚 Knowledge | Document ingestion config | Docs, repos, URLs to index |
| 🛠️ Tools | MCP servers and HTTP APIs | Custom tools and capabilities |
| ⚙️ Settings | Model routing and preferences | GPT-4, Claude, temperature settings |
| 🛡️ Permissions | Security policy enforcement | File access, network calls, secrets |
# Using the CLI (coming soon)
npx @dotaislash/cli init
# Or manually create
mkdir .ai
cd .ai
touch context.json
mkdir profiles rules agents tools// .ai/context.json
{
"version": "1.0",
"rules": ["rules/style.md", "rules/security.md"],
"context": ["src/**/*.ts", "docs/**/*.md"],
"agents": ["agents/code-reviewer.json"],
"settings": {
"model": "claude-sonnet-4",
"temperature": 0.7
}
}// .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
- Use TypeScript strict mode
- Prefer functional components
- Maximum line length: 100 characters
|
|
graph LR
A[Your Project] --> B[.ai/ Folder]
B --> C[VERSA Spec]
C --> D[Adapters]
D --> E[Cursor]
D --> F[Windsurf]
D --> G[Claude]
D --> H[Aider]
D --> I[Custom Tools]
- 📋 dotaislash-spec - This repository (canonical spec)
- 🔧 dotaislash-cli - Reference CLI tool
- 📐 dotaislash-schemas - JSON Schema definitions
- 📚 dotaislash-examples - Example configurations
- ✅ dotaislash-conformance - Test suite
- 🔌 dotaislash-adapters - Tool adapters
We welcome contributions! VERSA is built openly with the community.
- 💬 Join Discussions - Ask questions, share ideas
- 🐛 Report Issues - Found a problem? Let us know
- 📝 Propose Features - Have an idea? Open an RFC
- 🔧 Build Adapters - Support a new tool
- 📚 Improve Docs - Help others understand
# Clone the repository
git clone https://github.com/dotAIslash/dotaislash-spec.git
cd dotaislash-spec
# Read the spec
cat SPEC.md
# Check examples
cd examples/
# Run conformance tests (once available)
npm testSee CONTRIBUTING.md for detailed guidelines.
| Component | Status |
|---|---|
| Specification | 🟡 Draft (v1.0) |
| JSON Schemas | 🟡 In Progress |
| CLI Tool | 🟡 In Progress |
| Adapters | 🔴 Planned |
| Conformance Suite | 🔴 Planned |
| Documentation | 🟡 In Progress |
Legend: 🟢 Stable · 🟡 In Progress · 🔴 Planned
- ✅ Core specification
- ✅ Website launch
- ⏳ JSON Schemas complete
- ⏳ Reference CLI
- ⏳ Basic adapters (Cursor, Windsurf)
- 📦 npm packages published
- 🔌 Community adapters
- 📚 Comprehensive examples
- 🎓 Integration tutorials
- 🧪 Conformance certification
- 🤝 Tool vendor partnerships
- 📊 Usage analytics
- 🌍 Multi-language support
- 🔐 Advanced security features
- 🚀 Performance optimizations
Boring is Beautiful
VERSA uses plain JSON and Markdown. No DSLs. No magic. Just simple, portable formats that work everywhere.
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.
CC BY 4.0 © Alphin Tom
This specification is licensed under the Creative Commons Attribution 4.0 International License.
You are free to share and adapt this specification for any purpose, even commercially, as long as you provide appropriate attribution.
See LICENSE for full details.
- 🌐 Website: dotaislash.github.io
- 💬 Discussions: GitHub Discussions
- 🐛 Issues: GitHub Issues
- 👤 Author: Alphin Tom
Built with 🔥 by the dotAIslash community
⭐ Star us on GitHub · 🐦 Follow updates · 💬 Join the discussion