# INTENT.md — format definition

**INTENT.md is a Rendered Intent open format for portable product and
experience context.**

- Format name: `INTENT.md`
- Version: `0.1`
- Status: draft (open for revision; versioned changes only)
- Maintained by: Rendered Intent (renderedintent.com)
- Canonical definition: this document, at
  `https://renderedintent.com/intent-md.md`

## What it is

`INTENT.md` is a single Markdown file at the root of a project workspace. It
carries the current, usable product and experience intent — what must remain
true for the product, its users, its language, and its behavior — in a form
both people and agents can load before doing product, UX, interaction,
information-architecture, or product-copy work.

**Discovery rule (v0.1):** a project workspace has one active root
`INTENT.md`. Its `scope` field states the product or bounded area governed by
that file. Version 0.1 defines no nested `INTENT.md` files and no
inheritance, merging, or precedence between files.

It sits between two neighboring root interfaces:

- `AGENTS.md` — how people and agents should work in the repository. It owns
  repository operations, security handling, protected-content rules,
  deployment, generated-file custody, and agent workflow.
- `DESIGN.md` — how the approved visual identity and design system express
  the intent. It owns visual-system rules: tokens, composition, color,
  typography, and visual expression.

`INTENT.md` owns product purpose, user and context understanding, product
behavior, language, experience commitments, and product-level invariants.
Each constraint has exactly one owning interface; the others reference it
where it affects them rather than restating its operative rule.

`INTENT.md` is not another name for the project brain, and it does not replace
research, specifications, design files, or code. It is a concise,
current-context projection compiled from the project brain: the brain retains
the full evidence, history, debate, and superseded states; `INTENT.md` carries
what is currently true and points back to where each claim came from.

## Frontmatter

An `INTENT.md` file begins with YAML frontmatter carrying exactly these keys:

```yaml
---
format: INTENT.md
version: 0.1
status: draft | active | deprecated
scope: <the product or bounded area this file governs>
owners:
  - <role or accountable owner>
last_verified: YYYY-MM-DD
---
```

- `format` — always the literal `INTENT.md`.
- `version` — the format version this file conforms to (`0.1`).
- `status` — `draft` (being assembled, not yet authoritative), `active`
  (authoritative current intent), or `deprecated` (superseded; kept only for
  traceability).
- `scope` — the product or bounded area governed by this file, per the
  discovery rule above: one active root `INTENT.md` per project workspace.
- `owners` — one or more roles or named owners accountable for keeping the
  file true. A list, even when there is one owner.
- `last_verified` — the date the file's claims were last checked against
  their sources (`YYYY-MM-DD`). Verification is an act, not a formality: an
  old `last_verified` is a signal to re-check before relying on the file.

No other frontmatter keys are defined in version 0.1. Fields are added to the
format only with a clear operational purpose, via a version change.

## Required sections

The body contains these nine sections, as `##` headings, in this order. Every
section must be present and non-empty; a section with nothing established yet
says so explicitly (see Known unknowns) rather than being omitted.

1. **Product frame** — what the product is, who it serves, and the frame the
   team is operating under. The claims a new collaborator must hold before
   proposing changes.
2. **User models** — who the users are believed to be, and the standing of
   each claim: established by evidence, or a hypothesis awaiting it. Labeled
   honestly; never silently promoted.
3. **Conditions of use** — the situations, constraints, and contexts in which
   people actually encounter and use the product.
4. **Research-backed guardrails** — rules derived from research or evidence,
   recorded as guardrail records (below) with scope, confidence, and evidence.
   A research claim must not become a universal rule without both scope and
   evidence.
5. **Interaction contract** — the behavioral commitments the product makes:
   navigation, input, confirmation, recovery, accessibility, and the
   interaction qualities that must survive redesigns.
6. **Language and domain model** — the product's terms, what they mean, and
   the language rules that keep copy and interface coherent.
7. **Product invariants** — the statements that must remain true regardless
   of implementation; changing one is a product decision, not a refactor.
8. **Known unknowns** — the open questions, unvalidated assumptions, and
   uncovered cases, stated plainly. Agents and people encountering a case not
   covered by this file surface it here — they do not invent product intent.
9. **References** — pointers to the deeper record: research, decision logs,
   specifications, flows, components, `DESIGN.md`, and code. `INTENT.md`
   points; it does not copy wholesale.

## Guardrail records

Research-backed guardrails use this compact record shape, with identifiers
unique within the file:

```markdown
### G-001 — Guardrail title
- Status: active | provisional | superseded
- Scope:
- Confidence: high | medium | low
- Evidence:
- Rule:
- Exceptions:
```

- `Status` — `active` (holds now), `provisional` (adopted ahead of complete
  evidence, explicitly revisitable), or `superseded` (no longer operative;
  normally a superseded guardrail leaves the active file and remains
  traceable in the project brain).
- `Scope` — where the rule applies. A guardrail without a scope is a slogan.
- `Confidence` — how strongly the evidence supports the rule.
- `Evidence` — what supports it, with a pointer to the source. A guardrail
  without evidence is a hypothesis and belongs in Known unknowns or carries
  `provisional` status until evidence exists.
- `Rule` — the operative statement, in normative wording only where the
  format genuinely requires it.
- `Exceptions` — known cases where the rule does not apply.

## Format principles

- The file carries current usable intent; the project brain retains the full
  evidence, history, debate, and superseded states.
- Hypotheses remain visibly distinct from established findings.
- Research claims carry scope and evidence before they become rules.
- Agents surface uncovered or conflicting cases rather than inventing
  product intent.
- The file points to deeper research, decisions, specifications, flows,
  components, `DESIGN.md`, and code instead of copying them.
- Superseded guidance leaves the active file but remains traceable in the
  project brain.
- The format works for people as well as agents.

## Validation

A conforming validator checks, at minimum:

- frontmatter carries exactly the supported keys, with valid values;
- all required frontmatter fields are present;
- the nine required `##` headings appear, in order;
- every required section is non-empty;
- `last_verified` is a valid `YYYY-MM-DD` date;
- guardrail identifiers (`G-…`) are unique within the file.

## Versioning

This is version 0.1, a draft open format. Breaking changes increment the
version; files declare the version they conform to in frontmatter.

Open questions deliberately left out of 0.1, recorded for future versions
rather than answered ambiguously now: nested or per-feature `INTENT.md`
files, inheritance or merging across files, and precedence rules between
scopes. Feedback is welcome at hello@renderedintent.com.