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. The convention names the sections to write. This profile says when their content is ready for an agent to build against, with six readiness checks, the frontmatter that carries the verdict, and one command to check a file you already have. Readiness informs the decision to build; authorization remains a separate step.
Check your intent.md before Claude Code builds
Already using the intent.md format from Anthropic's AI-native SDLC playbook? Preflight reads it as written, at the repository root or in an intent/ folder, and shows which readiness checks still need attention. There is nothing to convert and no account, and the file stays on your machine.
# Intent: shipment status self-service Author: Sam. Status: draft. ## Problem Customers cannot check where their order is without phoning support. ## Proposed outcome Customers see shipment status and the expected delivery date in their account. ## Affected users and systems Customers, support agents, the shipment API. ## Constraints No new personal data on the account page. ## Open questions Should guest checkouts see it too?
✗ Preflight failed. 3/6 checks blocking.
✗ Fewer than two outcomes. Name at least two, one per line or paragraph, so each can be checked on its own.
↳ Read this. If it holds more than one outcome, separate them so each can be checked on its own:
"Customers see shipment status and the expected delivery date in their account."
✗ No edge case with a defined expected behavior.
✗ No concrete verification — describe at least one check specific enough to run.
✓ Title ✓ Objective ? Outcomes ✓ Constraints · Edge cases · VerificationAt this stage the playbook's file is meant to be a proto-spec, and it reads as one: the problem, the constraint and the title pass. The three open checks are what an implementing agent needs next: a second outcome that can be checked on its own, what should happen when something fails, and one check concrete enough to run.
# Intent: shipment status self-service Author: Sam. Status: draft. ## Problem Customers cannot check where their order is without phoning support. ## Proposed outcome - Customers see shipment status and the expected delivery date in their account. - Support calls asking where an order is drop by 30% within a month. ## Affected users and systems Customers, support agents, the shipment API. ## Constraints No new personal data on the account page. ## Edge Cases - **The shipment API is down**: the page shows the last known status and when it was checked. ## Verification - A test renders the status for a shipped order and for an order with no shipment yet. ## Open questions Should guest checkouts see it too?
✓ Preflight passed. 6/6 checks. Ready to hand to an agent. ✓ Title ✓ Objective ✓ Outcomes ✓ Constraints ✓ Edge cases ✓ Verification
The sections preflight does not grade, such as the author line, affected systems and open questions, stay as they are, and preflight never edits the file. The open questions still need a person to answer them. A passing verdict informs the decision to build; it does not authorize it.
npx @pathmode/cli preflight
Run it from the repository root. With several features in intent/, name one: npx @pathmode/cli preflight intent/shipment/intent.md. It exits 0 when ready and 1 when a check blocks, so the same command works in CI.
A repeatable check at the handoff
Later stages of an agent-driven lifecycle mostly have automated gates. 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.
The first artifact gets a person instead. Anthropic's playbook describes intent.md as "a proto-spec in the originator's own terms" , reviewed by the product owner before design begins. That review is where product judgment belongs. The profile adds something a single read cannot promise: the same bar on every file, at the moment it is handed to an agent to implement.
Deterministic checks give reviewers a repeatable starting point. They can flag missing content and language they cannot confirm, while people remain responsible for product decisions and authorization.
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
Resolves the six checks below, through passing content, applicable confirmations, or explicit human-approved waivers, and carries the verdict in readiness. Recompute the verdict against the current content before handoff. Passing checks does not guarantee that every product question is answered, and unresolved product choices can still block execution.
Accountable
Adds provenance: source pointing at the record the file was written from, and evidence linking the observations that back it. A Level 1 file records its readiness assessment. A Level 2 file lets you ask why anyone believed it, and find the answer somewhere other than the author's memory.
Schema validity, readiness, and authorization
Schema validity. The normalized document has the required fields and accepted types. It does not establish product quality or permission to implement.
Readiness. Missing content is absent; substantive content the heuristic cannot recognize is unconfirmed. Objective and outcome confirmations bind to the exact normalized text and must be renewed when that text changes. Missing content cannot be confirmed. Waiving either dimension requires explicit human approval and is reported as an exception, never as a passed check. When both are waived, product-intent preflight is not applicable to the change.
Authorization. Resolve blocking product choices and obtain the approval required by the owning workflow before implementation. A 6/6 readiness score does not authorize work. A status or attribution written in a local file is a claim; authenticated approval must be verified in the system that recorded it.
The six checks
Each check is computed from the file's own text by a pure function. No model call, no network. The same content and confirmation records produce the same verdict. These checks are heuristics: unconfirmed content may be meaningful text the check does not recognize.
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
Identity, a saved readiness assessment, and provenance. Verify the current content and approval in the source record before relying on them.
---
id: "intent_abc123"
version: 3
status: "approved"
readiness: "passed 6/6"
source: "https://pathmode.io/intent/intent_abc123"
evidence:
- type: "friction"
source: "support-ticket-4421"
excerpt: "Support ticket 4421 reports payment retry failures."
---
# 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. Appends "blocked by N unresolved product choice(s)" when a human still owes a decision the spec depends on. Confirmations count as passed; human-approved waivers are reported separately as exceptions. A saved verdict can become stale after edits: recompute it before handoff. |
productChoices | Extension | Durable choice records, including state and stable claim IDs. Readers recompute the execution block from these records; local saves preserve them. |
productChoiceReadinessUnknown | Extension | Preserves a block from an older file whose choice records are missing. Refresh the records from the source before implementation. |
source | Level 2 | URL of the record this file was written from. Declares the file a working copy, not the original. |
evidence | Level 2 | Optional array of evidence items, each with a type and excerpt. Use repo-safe summaries or references; an empty array records no linked evidence. |
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 /plugin install pathmode@pathmode /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.