AI coding tools increasingly need project-specific instructions, rules, and manifests. The challenge is that each environment may expect a different native representation. This article explains the architecture behind agent-compat: detection, adapter-based compilation, native output, and validation.
The problem
A project may need to communicate the same intent to multiple AI agent environments. Those environments can differ in file names, layouts, supported fields, and conventions.
The naive solution is to maintain every native file manually.
That solution creates drift.
A compiler-like workflow
I designed agent-compat around four steps:
detect → compile → write native files → validate
The source manifest represents project intent. An adapter translates that intent into the representation expected by a target environment. Validation then checks the generated result against the specification.
Why detection matters
A manual target flag assumes the user always knows which environment is present and which targets should be generated. Automatic detection can reduce that coordination cost and make integrations easier to embed.
Detection should not be confused with compilation. The system first determines context, then chooses the appropriate adapter and output strategy.
Why adapters matter
Each environment should not be hard-coded into the core workflow. Adapters isolate target-specific behavior:
- Native file paths
- Formatting rules
- Supported fields
- Output transformations
- Validation behavior
An open registry also creates a path for community-maintained adapters.
Why validation is first-class
Generation without validation is only half a workflow.
A generated file may exist but still be incomplete or stale. A validation API makes compatibility testable in code and usable in CI.
A useful report should help answer:
- Which target was detected?
- Which files were generated?
- Which checks passed?
- Which fields or outputs differ from the spec?
SDK versus CLI
The CLI is convenient for direct human interaction. The SDK is useful when another system needs to invoke compatibility programmatically.
That is why agent-compat is library-first. It can be embedded in developer tools, repository automation, and CI pipelines, while the companion CLI provides a straightforward terminal interface.
The output should be native files, not an abstract compatibility layer that every downstream tool must understand. Native output keeps the result close to the target environment while the validation report preserves visibility into what happened.
Early release
agent-compat is currently an early open-source project under the MIT license. The goal of the first release is to establish the model and discover real compatibility problems through usage.
Repository: https://github.com/JustineDevs/agent-compat
Installation & Setup
npm install @jstn-sdk/agents
import { Agents } from "@jstn-sdk/agents";
How It Works
1. Detect
Automatically discovers which agent environments are present in a project:
const detected = await Agents.detect("./my-project");
// → [{ id: "cursor", confidence: 0.95 }, { id: "codex-cli", confidence: 0.92 }]
2. Compile
Transforms a canonical manifest into native files for each environment:
const manifest = {
version: 1,
project: { name: "my-app", stack: ["typescript"] },
instructions: ["Run tests before completion"],
skills: { "code-review": { description: "Review PRs" } }
};
const result = await Agents.compile(manifest, {
targets: ["cursor", "codex-cli", "pi"],
output: "./my-project"
});
// → { files: [".cursor/rules/agents.mdc", "AGENTS.md", ".pi/skills/review/SKILL.md"] }
3. Validate
Checks generated files against official specifications:
const report = await Agents.validate("./my-project");
// → { cursor: "✓", "codex-cli": "✓", pi: "◐", summary: { ... } }
If you maintain instructions across multiple AI tools, what should a compatibility SDK validate first: file presence, schema correctness, semantic equivalence, or drift over time?
Top comments (0)