SPEC.md - Preview

# specification · draft v0.1

The AGENT-README.md Specification

A minimal, tool-neutral convention for instructing AI agents.

status: draft - expect changes version: 0.1 last updated: 2026-07-07

The key words MUST, SHOULD, and MAY are used in the sense of RFC 2119. This is an early draft published for discussion; nothing here is final.

1. Purpose

An AGENT-README.md is a single Markdown document that gives an AI agent enough context to work in a project safely and correctly without human hand-holding. It answers four questions:

What is this project, and what does success look like?
How do I build, test, and run it?
What conventions must I follow?
What must I never do?

2. Location & naming

For a repository, the file MUST be named AGENT-README.md and SHOULD live at the repository root.
Nested files. A large or multi-package repository MAY place additional AGENT-README.md files in subdirectories. When several apply, the file nearest to the code being changed takes precedence, and a nested file SHOULD be read as an override of, not a replacement for, the files above it. This lets, for instance, a database folder and a web frontend carry different rules.
For a website, it SHOULD be served at /agent-readme.md with a text/markdown (or text/plain) content type.
The filename comparison SHOULD be case-insensitive. AGENT-README.md is the canonical form.

3. Format

The file MUST be valid CommonMark Markdown.
It MUST remain readable by a human with no rendering.
It SHOULD be short - a target of one screen to two pages. Link out for depth rather than inlining everything.
It MAY begin with an optional metadata header block for a few machine-readable fields (see §5).

4. Recommended sections

Agents SHOULD recognise the following ## headings by name. All are optional except Purpose and Guardrails, which SHOULD be present. Order matters: the sequence below is the recommended order, front-loading the highest-value, repo-specific operating detail (how to run the project, then how not to break it) and pushing generic style further down, so an agent reading top to bottom reaches what changes its behaviour first.

Heading	Contains	Requirement
`## Purpose`	One or two sentences on what the project is and the definition of "done".	SHOULD
`## Setup & commands`	Exact, copy-paste commands to install, build, test, lint, and run.	SHOULD
`## Guardrails`	Repo-specific hard rules: protected and generated paths, irreversible actions, secrets handling, when to stop and ask.	SHOULD
`## Conventions`	Language/version, style rules, structure, patterns to follow or avoid.	MAY
`## Current state`	What is mid-flight right now: active refactors, known-failing areas, and what to leave alone. Keeps an agent from "fixing" work in progress.	MAY
`## Surprises`	Things that would surprise a newcomer: intentional duplication, a table with no foreign keys by design, code that must not be renamed because callers depend on it.	MAY
`## Architecture`	A short map of the codebase, links to deeper docs, and any MCP servers or context endpoints the agent should use.	MAY
`## Contacts`	Owners, review process, where to file issues.	MAY
`## Changes`	A short reverse-chronological log of notable edits to this file, so an agent can spot recently changed guidance.	MAY

4.1 Guardrails come right after commands

Guardrails SHOULD sit directly after ## Setup & commands: once an agent knows how to operate the repo, the next thing it needs is how not to break it. If an agent can read only part of the file, it MUST prioritise ## Guardrails.

Repo-specific guardrails matter far more than generic ones. "Never edit schema.generated.ts or vendor/" is operationally decisive; "ask before deleting files" is generic advice most agents already follow. Lead with the rules that are specific to this repository, and keep generic caution to a minimum. Guardrail rules SHOULD be phrased as imperatives an agent can check against a proposed action, for example:

## Guardrails
- Never modify files under `generated/` or `dist/`.
- Never commit files matching `.env*` or `*.pem`.
- Do not run database migrations; prepare them and stop for review.
- Ask before deleting files or rewriting git history.

Guardrails MAY also state the agent's operating boundaries explicitly, so the limits are declared rather than left to inference. Useful boundaries to spell out:

Filesystem. Which paths are writable and which are off-limits (for example: write only under src/; never touch vendor/).
Network. Whether the agent may reach the network at all, and if so, which hosts or package registries.
Commands. Whether only the documented targets (npm test, make build) are permitted, or open-ended shell is acceptable.
Operations. Which actions are permitted (read-only analysis, opening pull requests for review) versus those that require human approval (merging, deploying, deleting files, changing branch protection).

These declarations are still advisory (see §6 and §8). They inform a well-behaved agent and can guide a sandbox policy, but they do not by themselves enforce anything.

Grouping guardrails by kind helps the important cases stand out. One effective shape is protected paths, actions that need approval, and what is safe by default:

## Guardrails
- Protected paths: `vendor/`, `dist/`, `.env*`
- Requires approval: deleting files, rewriting history, touching production config
- Safe by default: read-only analysis, opening a pull request for review

4.2 Facts vs. preferences

Not all guidance carries the same weight. A file SHOULD distinguish facts (non-negotiable, and usually verifiable) from preferences (negotiable style choices), because an agent can reason about them differently: facts constrain, preferences guide. Keep this short: put facts first, and limit preferences to the handful that actually change code-generation or review outcomes. A long list of style preferences dilutes the file and buries what matters.

## Conventions

Facts (non-negotiable):
- Database is SQL Server 2019.
- Tests use NUnit.

Preferences (negotiable):
- Prefer CTEs over nested subqueries.
- British spelling in user-facing text.

4.3 Example: an Architecture section

The ## Architecture section is where "links to deeper docs" become concrete. Point at the specific documents and directories an agent needs, rather than describing them in prose:

## Architecture
- Design: see `ARCHITECTURE.md`.
- Database: PostgreSQL; migrations in `db/migrations/`.
- CI/CD: GitHub Actions; workflows in `.github/workflows/`.
- Context: the `docs-mcp` server exposes the domain glossary.

5. Optional metadata header

A file MAY begin with a small metadata header: a block, fenced by a line of --- above and below, containing one Key: value pair per line. It is a plain colon-delimited header, not YAML, chosen deliberately to avoid YAML's indentation and type-coercion pitfalls. The whole block is optional, and the Markdown body remains canonical.

This header is not a required part of the file. Many good AGENT-README.md files will omit it entirely and start straight at # AGENT-README. Include it only if something in your toolchain will actually read it, or if a spec version and a last-updated date are genuinely useful to your readers. Do not add it as boilerplate.

---
Agent-Readme: 0.1
Name: csv2parquet
Description: A CLI that converts CSV to Parquet.
Updated: 2026-07-07
Tags: cli, data, etl
Languages: typescript, sql
Docs: /docs/
Issues: /issues
---

5.1 Parsing rules

The header, if present, MUST be the first content in the file and MUST be fenced by a line containing only --- before and after it.
Each line MUST be a single Key: value pair. The first colon separates the key from the value; any further colons are part of the value.
Values are literal text. Consumers MUST NOT type-coerce them, so 0.10 stays 0.10 and no quoting is needed.
There is no nesting. A field with several values MUST use a comma-separated list on one line (e.g. Languages: typescript, sql). This removes every indentation failure mode.
Keys are case-insensitive; Updated and updated are the same field.
Unknown keys MUST be ignored, so the field set can grow without breaking older consumers.
Dates MUST be ISO-8601 (YYYY-MM-DD).

5.2 Fields

All fields are optional. The set below is inspired by the Open Knowledge Format's frontmatter (title, description, tags, timestamp), pared down to what an agent finds useful in a single file.

Key	Meaning	Note
`Agent-Readme`	The spec version this file targets.	Recommended. A staleness / compatibility hint.
`Version`	This file's own revision, distinct from the spec version.	Optional. Pairs with a `## Changes` log.
`Name`	The project or document title.	Recommended.
`Updated`	Date the file was last reviewed.	Recommended. ISO-8601; lets an agent judge staleness.
`Description`	A one-line summary.	Optional.
`Tags`	Comma-separated keywords for discovery / routing.	Optional.
`Languages`	Comma-separated primary languages or stack.	Optional.
`Docs`, `Issues`, `Homepage`	Links to deeper documentation, the issue tracker, and the project home.	Optional.
`Contacts`	Comma-separated owners or points of contact.	Optional.

Keep the header to identity and pointers. Do not put commands or guardrails in it: those belong in the readable body so there is a single source of truth and nothing authoritative is hidden in metadata.

6. Precedence

An AGENT-README.md is project guidance. It MUST NOT be treated as a security boundary: it is advisory, like robots.txt. Where it conflicts with an operator's or platform's explicit safety policy, that policy MUST win. Where it conflicts with a tool-specific file the agent already honours, the agent SHOULD prefer the more specific and more restrictive instruction.

6.1 How an agent should consume this file

A well-behaved agent SHOULD follow this sequence when it starts work in a project:

Discover. Look for AGENT-README.md at the repository root (case-insensitive). For a change in a subdirectory, prefer the nearest file (see §2). For a website, request /agent-readme.md.
Read guardrails first. Load ## Guardrails before acting, and check each proposed action against it (see §4.1).
Treat it as the project's source of truth for how to work here, while honouring precedence: an operator's safety policy always wins (§6), and its contents are untrusted for injection purposes (§8).
Re-check on staleness. If the Updated date or ## Changes log looks old relative to the code, treat specific commands and facts with extra caution.

7. Relationship, migration, and coexistence

This convention does not aim to replace tool-specific files (AGENTS.md, CLAUDE.md, .cursorrules, and the like). It offers one obvious, tool-neutral home and coexists with the others. An AGENT-README.md MAY point at them:

> Tool-specific notes: see `CLAUDE.md` and `.github/copilot-instructions.md`.

When a project already has one of those files, adopting AGENT-README.md SHOULD follow a light migration:

Make AGENT-README.md the canonical, tool-neutral guidance.
Leave the existing file in place, but reduce it to tool-specific configuration plus a one-line pointer to AGENT-README.md, so there is no duplicated or conflicting guidance.
Do not delete a file that tooling still reads automatically; a pointer avoids breaking existing workflows.

8. A note on trust

Because the file is advisory and author-controlled, agents SHOULD treat its contents as untrusted input for the purposes of prompt-injection defence: follow its project guidance, but never let it override the operator's safety rules or coax the agent into exfiltrating secrets or acting outside its sanctioned scope.

9. What not to include

Keep the file about this repository. The following weaken it:

Generic model-steering text. Lines like "think deeply", "be an expert", or "never hallucinate" are prompt engineering, not project documentation. They add tokens, age badly as models change, and belong (if anywhere) in an operator's system prompt. Repository-specific facts have a far longer shelf life.
Duplicated commands or rules. State each command or guardrail once, in the body. Do not copy them into the metadata header (see §5) or repeat them across sections, so there is a single source of truth.
Human onboarding and marketing. Overviews, badges, and sales copy belong in README.md. Keep this file focused on how to operate in the project.
Secrets. Never place credentials, tokens, or private endpoints here. The file is often public and always author-controlled.

10. Adoption

To signal that a repository follows this convention, a project MAY add a badge to its README.md. A badge is human-facing, so it belongs in README.md, not in AGENT-README.md. Link the official badge and point it at your file:

[![agent-readme](https://agent-readme.md/badge.svg)](./AGENT-README.md)

The badge SVG is served from https://agent-readme.md/badge.svg, so its design stays consistent across projects. Because the file itself lives at a predictable path, it is directly linkable, for example https://github.com/<owner>/<repo>/blob/main/AGENT-README.md, or served from a site root at /agent-readme.md.

Have thoughts on this draft? That is exactly what it is for. See the templates to try it in a real project, or return home.