Conformance profile
intent.md is the first artifact.
This is the bar it has to clear.
The AI-native lifecycle now starts with an intent file: a human writes down what they want, an agent builds against it. That is the right shape. But an intent file is only worth what it says, and nothing in the convention says what it has to say. This page is the profile that fills the gap: six checks a file must pass before an agent builds against it, the frontmatter that carries the verdict, and one command to check a file you already have.
Every stage after intent.md has a gate
Look at how an agent-driven lifecycle is actually governed. The build stage waits for an approved plan. Hooks allow, ask, or block. Tests run before a human reads the diff. Production deploys require a named authorization. Each of those is a real gate, and none of them is a matter of opinion.
Then look at the first artifact. Anthropic's playbook describes it as "a proto-spec in the originator's own terms" , approved by a product owner before design begins. Approval by a person is the only check it gets, which means the quality of everything downstream rests on the one step with no floor under it. A vague objective passes review on a busy Thursday, and every gate after it faithfully enforces the wrong thing.
A gate that depends on who is reading, and how tired they are, is not a gate. The fix is not more review. It is a floor cheap enough to run every time, and identical for everyone who runs it.
Three levels of conformance
A profile is useful only if a file can fail it. These levels are cumulative, and most files in the wild sit at Level 0.
Parses
Valid Markdown with YAML frontmatter carrying id, version, and status. A machine can read it, identify it, and tell whether it changed. This is table stakes, and it says nothing about whether the content is any good.
Buildable
Passes all six checks below, and carries the verdict in readiness. An agent reading this file knows what done means without asking a follow-up question, and a reviewer can see the verdict without recomputing it. This is the level that matters for handoff.
Accountable
Adds provenance: source pointing at the record the file was written from, and evidencecounting what backs it. A Level 1 file tells you it is clear. A Level 2 file lets you ask why anyone believed it, and find the answer somewhere other than the author's memory.
The six checks
Each check is computed from the file's own text by a pure function. No model call, no network, no judgment call at read time. Run it twice on an unchanged file and the answer is identical, which is what makes a passing verdict evidence rather than an opinion.
titleA specific noun phrase, at least two words, not a placeholder.
objectiveNames who is affected and what concretely fails or becomes possible for them. Buzzwords with no number are rejected even when the sentence is long.
outcomesAt least two, and at least two thirds of them stated as a threshold, an observable capability, or a concrete state change.
constraintsAt least one statement an implementation could actually violate. Bare adjectives are not constraints.
edgeCasesAt least one scenario paired with the behavior expected when it happens.
verificationAt least one check concrete enough to run without asking the author what they meant.
These thresholds are calibrated against a corpus of real and synthetic specs, not chosen by taste. A check that rejects everything is as useless as one that accepts everything, so the published exemplars on this site all pass their own gate.
The frontmatter
Everything a reader needs in order to trust the file, in the first eight lines of it.
--- id: "intent_abc123" version: 3 status: "approved" readiness: "passed 6/6" source: "https://pathmode.io/intent/intent_abc123" evidence: 4 --- # Checkout payment retry ...
| Key | Level | What it is for |
|---|---|---|
id | Level 0 | Stable identity. Survives edits, so two saves of the same intent are one history rather than two files. |
version | Level 0 | Increments on each save. A reviewer can tell whether the file moved since they last read it. |
status | Level 0 | Lifecycle state (draft, approved, and so on). Preserved across saves rather than reset. |
readiness | Level 1 | The deterministic verdict: "passed 6/6", or "failed N/6" naming the blocking gates. Recomputed on every write, so it cannot go stale. |
source | Level 2 | URL of the record this file was written from. Declares the file a working copy, not the original. |
evidence | Level 2 | How many pieces of evidence back the spec. Zero is a legitimate answer, and a visible one. |
A failing verdict is not an error. A file that fails should still be written, still be committed, and still say so in its frontmatter. The gate reports; the person decides. A profile that blocks people from saving their own draft gets removed within a week, and then there is no floor at all.
Checking a file you already have
Three ways, none of which needs an account. The verdict is the same in all three, because they run the same functions.
In Claude Code
Adds a /preflight command that reads the intent.md in your repo, names the blocking gates, and repairs them one question at a time. Keyless: your spec stays in your repo.
/plugin marketplace add pathmodeio/claude-plugin /preflight
In any MCP client
The server exposes check_intent_readiness, and every save stamps the verdict into the file's frontmatter.
npx -y @pathmode/mcp-server@latest setup
Schema conformance is a separate, complementary check: validate-intentspec-action enforces shape in CI, while the profile above judges content. A file can be schema-valid and still say nothing.
The file is a working copy
A file in a repository is scoped to that repository and ends when the feature does. The judgment it describes does not. The same decision constrains the next three features, gets revisited when something contradicts it, and needs to be answerable months later when nobody remembers the meeting.
So source is the load-bearing key at Level 2. It says this file was written from a record that outlives it, and points at where that record lives. Commit the file, hand it to the agent, delete the branch: the reasoning is still somewhere, with the evidence attached and the history intact.
You do not need a hosted record to write a conformant file. A hand-authored intent.md with no source can pass all six checks and reach Level 1, which is the level that matters for handing work to an agent. Level 2 is for teams who need to answer the question a year from now.