Where the file sits
Is there a standard format for intent files in a repository?
Ask a coding assistant and it will say AGENTS.md, then add that no formal, machine-readable intent specification exists. Half of that is right. AGENTS.md is the de facto standard for telling an agent how to work in a repository. It says nothing about what any particular change is for.
The complete picture is three layers, each with its own file. This page puts them side by side, says plainly what each one does and does not do, and shows how they sit in one repository together.
Three layers, three questions
Repo instructions
AGENTS.md · CLAUDE.md · .cursor/rulesHow do I work in this codebase?
Build and test commands, conventions, architecture notes, things never to touch. One per repository, long-lived, read on every task. AGENTS.md is deliberately plain Markdown with no required fields; CLAUDE.md is the same idea for Claude Code; Cursor reads rule files with a small frontmatter. This layer is settled and IntentSpec does not compete with it.
Product intent
intent.md · IntentSpecWhat is this change for, and what must be true when it is done?
Who is affected and what goes wrong for them today, the observable outcomes, the constraints someone could actually violate, the edge cases with their expected behavior, how each outcome will be verified, and the evidence behind the call. One per change. This is the layer that had a convention (a proto-spec, approved by a person) and no format. IntentSpec is the format: a JSON Schema, a normative spec and a conformance corpus.
Implementation spec
Spec Kit · OpenSpec · Kiro specsWhat exactly do we build, in what design, in which tasks?
Requirements broken into scenarios, a technical plan or design, and an ordered task list the agent executes. Spec Kit, OpenSpec and Kiro each define a folder layout and a workflow for this. They differ in whether they favour greenfield or existing codebases and in how much ceremony they impose. All three start from a description of the change. intent.md is that description, in a form a validator can check.
Side by side
Structural facts only: what each format writes, what it requires, what checks it. Nothing here is a judgment about which workflow produces better software. Where a tool changes its layout, the row is wrong and should be corrected on GitHub.
| AGENTS.md / CLAUDE.md | intent.md (IntentSpec) | Spec Kit | OpenSpec | Kiro specs | |
|---|---|---|---|---|---|
| Layer | Repo instructions | Product intent | Implementation spec | Implementation spec | Implementation spec |
| Unit | One per repository | One per change | One folder per feature | One folder per change, archived into specs/ | One folder per feature |
| Answers | How to work in this codebase | What problem, for whom, what must be observably true, how anyone will know | What to build and in which tasks | What changes in the current spec, and the tasks | Requirements, design and tasks for a feature |
| Files | AGENTS.md, CLAUDE.md, .cursor/rules/*.mdc | intent.md (or JSON) | .specify/memory/constitution.md, specs/NNN-name/spec.md, plan.md, tasks.md | openspec/specs/**, openspec/changes/<id>/proposal.md, design.md, tasks.md, specs/** deltas | .kiro/specs/<feature>/requirements.md, design.md, tasks.md, .kiro/steering/*.md |
| Required fields | None. Free-form Markdown. | id, status, objective, outcomes | Template sections; none enforced by a schema | Structure checked by the CLI (openspec validate) | Template sections; none enforced by a schema |
| Machine-readable schema | No | Yes, JSON Schema at a canonical URL | No | No published schema; CLI-checked structure | No |
| Conformance corpus | No | Yes, valid and invalid fixtures plus a normalization corpus | No | No | No |
| Evidence and provenance | None | Typed evidence items anchored to outcomes, constraints and edge cases | None as a field | None as a field | None as a field |
| Verification | Test commands, by convention | verification: how each outcome is confirmed | Acceptance scenarios in spec.md | Scenarios per requirement in spec deltas | EARS acceptance criteria in requirements.md |
| Who usually writes it | Engineers | Product and engineering together, or an agent from evidence | Engineer with the agent | Engineer with the agent | Engineer with the agent |
| Lifetime | Long-lived, edited in place | Until the change is verified | Per feature | Until archived into the living spec | Per feature |
| Governance | agents.md, open convention | MIT, standards repo, versioned spec and profile | GitHub, MIT | Fission-AI, MIT | AWS, part of the Kiro IDE |
One repository, all three
The files do not compete for the same slot. A repository that uses all three looks like this, and the arrows are the order things are read: the agent learns how to work here, then what this change is for, then what to build.
my-repo/ ├── AGENTS.md # 1. how to work here (long-lived) ├── intent.md # 2. what this change is for (per change) ├── openspec/ # 3a. OpenSpec: proposal → specs → design → tasks │ └── changes/retry-failed-syncs/ │ ├── proposal.md # derived from intent.md by the adapter │ ├── design.md │ ├── tasks.md │ └── specs/sync/spec.md ├── specs/001-retry-failed-syncs/ # 3b. or Spec Kit: spec.md, plan.md, tasks.md ├── .kiro/specs/retry-failed-syncs # 3c. or Kiro: requirements.md, design.md, tasks.md └── src/
With OpenSpec. The pathmode-intent adapter reads intent.md and writes the change folder: a proposal, a spec delta and the verification contract in tasks.md. The proposal inherits the objective and outcomes instead of restating them from memory.
With Spec Kit. Hand intent.md to /speckit.specify as the feature description. The outcomes become the acceptance scenarios, the constraints belong in the constitution, and the edge cases are the ones Spec Kit would otherwise mark as needing clarification.
With Kiro. Each outcome maps to a requirement in requirements.md, and each edge case already carries the expected behavior an EARS acceptance criterion needs.
With none of them. intent.md next to AGENTS.md is enough for a coding agent to know both how to work and what done means. Add an implementation-spec workflow when the how needs governing across a team.
What is different about a format, as opposed to a layout
Spec Kit, OpenSpec and Kiro define folder layouts and templates. That is the right tool for governing a workflow. IntentSpec defines a validated model, which is the right tool for a file that many consumers read and none of them wrote.
- A required floor.
id,status,objective,outcomes. A file without them is a draft, not a document. - Evidence with anchors. Each evidence item can point at the outcome, constraint or edge case it justifies. A reviewer can ask why a requirement exists and get an answer from the file.
- A repo-safe profile. A committed document must not carry raw customer quotes, names, transcripts, confidential metrics or secrets. Excerpts are summaries or references. The profile is versioned separately from the schema.
- Two serializations, one model. Frontmatter-only and sectioned Markdown normalize to the same object, and a normalization corpus pins the result so two readers cannot agree a file is valid while disagreeing about what it says.
- Small on purpose. No CLI, no lifecycle, no task format. Those belong to the workflows above. IntentSpec is the input they share.
Short answers
Is there a standard format for AI agent intent files in a repository?+
Not one that covers everything. Repo instructions have a de facto standard in AGENTS.md (with CLAUDE.md and Cursor rules as tool-specific equivalents). Implementation specs have several competing workflows: GitHub Spec Kit, OpenSpec and Kiro specs, each with its own file layout. Product intent, the layer that says what problem is being solved, for whom, and what must be observably true when it is done, has IntentSpec: a JSON Schema, a conformance corpus, and intent.md as the conventional filename.
Does intent.md replace AGENTS.md or CLAUDE.md?+
No. AGENTS.md and CLAUDE.md describe the repository: how to build, test and behave in this codebase. They are long-lived and apply to every task. intent.md describes one change: the outcomes, constraints, edge cases, verification and the evidence behind them. A repository carries one AGENTS.md and an intent.md per change.
Does intent.md replace Spec Kit, OpenSpec or Kiro specs?+
No. Those workflows start where intent.md ends. Spec Kit turns a description into spec.md, plan.md and tasks.md. OpenSpec turns a change into a proposal, spec deltas, a design and tasks. Kiro turns a feature into requirements.md, design.md and tasks.md. intent.md is the upstream input each of them reads: it fixes what done means before any of them decides how to build it. An adapter carries intent.md into an OpenSpec change folder.
What does IntentSpec have that the others do not?+
A published JSON Schema with a canonical URL, a conformance corpus that any implementation can run, a typed evidence field with anchors from each requirement back to what justified it, a required-field floor (id, status, objective, outcomes), and a repo-safe profile that says what must never be committed. The others define file layouts and templates; IntentSpec defines a validated model.
Which one should a team adopt first?+
AGENTS.md first, because every coding agent reads it and it costs an afternoon. Then intent.md for any change where the risk is building the wrong thing rather than building it badly. Pick an implementation-spec workflow when the how needs governing across a team; intent.md feeds whichever one you choose.
Start with the file
Copy the starter from the home page, save it as intent.md at the repository root next to your AGENTS.md, then check it. The check runs locally, needs no account, and writes nothing.
npx -y @pathmode/cli preflight
Read the specification, browse the conformance corpus, or propose a correction to this page on GitHub.