adl: Instructions file for Codex

AGENTS.md

This repository is the source of truth for the ADL (Agent Definition Language) JSON Schema. The only shipped artifact is schema/v1/schema.json (JSON Schema Draft-07, apiVersion: adl.inference-gateway.com/v1). There is no application code. The second surface is the docs site under docs/ (VitePress), published to adl.inference-gateway.com/v1. README.md covers ADL concepts and the manifest format, and CONTRIBUTING.md covers setup, versioning, and releases in depth.

Layout

• schema/v1/schema.json — the canonical schema. Everything else describes it.
• docs/ — VitePress site (docs/guide/, docs/reference/, docs/examples/). Deployed by the Deploy workflow on any push to main touching docs/** or schema/v1/schema.json.

Commands

Recommended environment: flox activate (provides task, Node.js, Prettier, ajv). Manual setup: Node.js 24.x, then npm install --no-save ajv@8 ajv-cli@5 ajv-formats@3 — there is no package.json on purpose and the install is a one-off local to the working tree. Never commit node_modules/.

• task compile — AJV-compile the schema (the exact check CI runs)
• task validate -- path/to/manifest.yaml — validate a manifest against the schema
• task format / task format:check — Prettier auto-format / check (CI runs npx --yes [email protected] --check .)
• npx ajv compile --spec=draft7 -c ajv-formats -s schema/v1/schema.json — manual fallback without go-task
• Docs (inside docs/, which has its own package.json and lockfile): npm ci, then npm run dev / npm run build — the build must succeed before deploy

CI has two checks, both must pass: Compile JSON Schema (AJV) and Check formatting (Prettier, repo-wide including docs/). A .githooks/pre-commit hook runs Prettier on staged files. Activate once per clone with git config core.hooksPath .githooks. If it blocks a commit, fix with npx [email protected] --write <file>.

Schema versioning contract — the most important rule