Skip to main content

Portable AI Coding Knowledge with ARES

Project overview of ARES — the reference CLI for the AI Repository Standard that composes provider-specific artifacts from a canonical .ai/ source.

5 min read·Intermediate·Concept·Jul 18, 2026
projectdeveloper toolsai coding

Portable AI Coding Knowledge with ARES

What Was Built​

ARES (AI Repository Standard) is a Go CLI that lets repositories define durable AI coding knowledge once in .ai/, then generate provider-specific files for Cursor, GitHub Copilot, Claude Code, OpenAI Codex, and Antigravity. The golden rule: delete generated provider files, run ars compose, and everything regenerates from .ai/.

The Problem​

Teams adopting AI coding tools accumulate fragmented knowledge: rules in .cursor/, instructions in .github/copilot-instructions.md, CLAUDE.md, AGENTS.md — each drifting independently. Switching tools means rewriting knowledge. Multi-tool teams maintain duplicate, inconsistent copies.

Architecture Summary​

ARES is a local, file-based CLI — not an agent runtime, workflow engine, or web app.

Evolution and Milestones​

MilestoneWhat shipped
ARS v1 spec.ai/ directory format defined in SPEC.md
Core CLIars init, ars validate, ars compose, ars import
Multi-provider composeCursor, Copilot, Claude, Codex targets
Skills refactor (PR #7)Restructured .ai/skills/ format and validation
Antigravity support (PR #8)Compose and import for Antigravity provider
Release binariesmacOS, Linux, Windows via GitHub Releases

Key Decisions​

DecisionRationale
.ai/ as single source of truthProvider files are generated, never hand-maintained
Import + compose symmetryTeams can migrate from any existing provider format
Local CLI onlyNo server, no database, no agent runtime
ars validate in CICatch structural drift before merge
Preserve existing AGENTS.mdCodex compose skips overwrite if file already exists

Repository Format​

.ai/
  manifest.yaml                 project metadata
  instructions/<name>.md         repository-wide instructions
  agents/<name>/AGENT.md         agent role, responsibilities, boundaries
  skills/<name>/SKILL.md         reusable knowledge
  prompts/<name>.md              reusable prompt templates

Lessons Learned​

  1. Generated artifacts are disposable — if you hand-edit .cursor/rules/, you will lose changes on next compose. Edit .ai/ instead.
  2. Import before compose when migrating — ars import cursor brings existing rules into .ai/ without rewriting from scratch.
  3. Validate in CI — ars validate --json catches broken references before they reach every developer's machine.
  4. Provider parity is the goal — one knowledge tree, many tool outputs.

Sources​