Skip to content

agent-contract.md

Latest commit

 

History

History
78 lines (58 loc) · 2.93 KB

agent-contract.md

File metadata and controls

78 lines (58 loc) · 2.93 KB
Raw
title Agent contract
kind reference
audience
contributor
maintainer
agent
canonical_for
agent_contract
requires

Agent contract

Enforced by scripts/validate_agents.py, run by just check-agents and by a pre-commit hook. AGENTS.md is the single source of truth for how an agent works in this repository; everything else in the agent surface exists only so a particular tool can find it.

The four surfaces

Path Role
AGENTS.md Canonical. Read natively by Codex, and by anything following the convention.
CLAUDE.md A pointer, byte-pinned to @AGENTS.md and nothing else.
.github/copilot-instructions.md A pointer, byte-pinned to one paragraph.
.agents/skills/ Canonical task procedures, mirrored by thin bridges under .claude/skills/ and .codex/skills/.

A CODEX.md at the repository root is forbidden: Codex reads AGENTS.md directly, and a second file would be a second source of truth.

What AGENTS.md must contain

  • At least 300 words.
  • Six phrases, each naming an invariant that is expensive to rediscover: untrusted, just check, explicit authorization, ai_tmp/, docs/specs/, and runes.

The phrase list is a crude check and is meant to be. It does not verify that the guidance is good; it verifies that the six topics were not dropped in an edit.

What a skill must be

Frontmatter of exactly two keys:

---
name: svelte-change
description: Implement or review a Svelte route or component change with accessibility, rendering, and port-boundary evidence.
---
  • name equals the directory name.
  • description is at least eight words and states a real trigger.
  • The body cites AGENTS.md and names at least one just recipe. A procedure that ends without saying how to verify it is not a procedure.

What a bridge must be

Each of .claude/skills/<name>/SKILL.md and .codex/skills/<name>/SKILL.md carries the canonical frontmatter verbatim, then one sentence pointing at ../../../.agents/skills/<name>/SKILL.md — exactly one such reference, and at most forty words in total. A bridge that grows content of its own fails.

The inventory

The validator lists managed files from Git, honouring only this repository's .gitignore, and compares that against what it expects.

  • Every expected file must exist. A skill without its two bridges fails.
  • No unexpected file may exist under .agents/, .claude/ or .codex/. The single exception is .claude/settings.json, which is tolerated but not required — it carries provider configuration rather than agent guidance.
  • Managed files must be regular files, never symlinks.

Local assistant state stays out of the inventory by being listed in .gitignore. That is deliberate: the check reads Git rather than walking the filesystem, so an ignored file is invisible to it.

Related pages