An open format for product intent: what a change is for, who it affects, what must be true when it is done, and how anyone will know it worked.
Its conventional file is intent.md. If you only take one thing from this repository, take the
filename and the four questions.
This repository uses the format for its own product boundary: read its intent.md.
- Specification: SPEC.md (v1.2, normative)
- JSON Schema: schema.json, also served at
https://intentspec.org/schema.json - Human-readable site: intentspec.org
Product decisions get made in conversations, tickets, and heads, and then an agent or a new engineer builds from a description that no longer carries the reason. IntentSpec is a small, portable place to put the reason, in a shape that both people and tools can read.
objective: who is affected and what goes wrong for them today
outcomes: what observably changes
constraints: what must never happen
edgeCases: failure modes, each with its expected behavior
verification: how you will know it workedIntentSpec is not a workflow. It does not describe how work is proposed, reviewed, broken into tasks, or shipped, and it does not ship a CLI that runs your project.
Workflows that do those things consume it. OpenSpec is a
complete change workflow whose lifecycle starts at the proposal; IntentSpec sits upstream of that,
and the pathmode-intent adapter carries an
intent.md into it:
IntentSpec open product-intent format
└── intent.md the concrete adoption artifact
├── Pathmode authoring, evidence, provenance
└── pathmode-intent adapter into OpenSpec
intent.md -> proposal -> specs -> design -> tasks
Other adapters are welcome, including ones nobody here wrote.
intent.md usually lives in a git repository, which means everyone who clones it can read it,
permanently. SPEC.md section 4 defines the repo-safe
profile normatively: summaries and references in the committed file, raw evidence and
authenticated attribution somewhere that can actually protect them.
This matters because the schema requires an excerpt on each evidence item, which read literally
invites pasting the source material. In a repo-safe document the excerpt is a ticket id, a
dashboard name, a link, or a one-line paraphrase.
An implementation conforms if it accepts everything in conformance/valid/ and rejects everything
in conformance/invalid/. Each invalid fixture states what it violates.
npm install
npm testConformance is about the format only. It cannot tell you whether a document contains good product judgment, which is not a property a schema can check.
Proposals, corrections, and adapter links are welcome: see CONTRIBUTING.md and GOVERNANCE.md. The format is stewarded by Pathmode and usable by anyone under MIT, including by tools that compete with it.
MIT.