Skip to main content
intent.mdv1.2
[H]How it works[V]Validate[S]Spec[F]The fileSchema[G]GitHubRead the spec

your-repo/intent.md · Open format · Schema-validated · v1.2

The evidence-backed definition of done.

Your agent knows how to build. intent.md tells it what done means and why: outcomes, edge cases, and the evidence behind them, in one file any coding agent can read.

Start
Grade

Validates the schema and grades readiness with a deterministic six-check verdict. Runs locally, free, no account, writes nothing.

Read the spec·Validate one in the browser [V]

intent.md · excerpt of the starteryaml
---
objective: "Allow users to export filtered data to JSON"
evidence:
  - type: "quote"
    source: "support-ticket-4421"
    excerpt: "I can't tell what's in my export before I download it. Last time it was empty."
    anchors: ["outcome:1", "edgeCase:0"]
outcomes:
  - "Users can export the filtered dataset as a JSON download"
  - "The export contains only the currently filtered rows, never the full dataset"
  - "The output never includes PII fields"
---
anchors:The support-ticket quote names the outcome it justifies. The agent gets concrete criteria; the reviewer gets the reason each one exists.
Full field reference →

readable by claude-code · cursor · windsurf · copilot · aider · any-llm

Format
Markdown + YAML frontmatter
Schema
JSON Schema, enforced in CI
Version
v1.2, versioned changelog
Tooling
GitHub Action · CLI · web validator
Account
None needed
Lock-in
None. Plain text in your repo

A spec that can't say why is just an opinion.

The same request, handed off twice.

What the agent usually gets

ticket

Add JSON export

Users have been asking for this. Should be quick, just dump the table to a file.

The agent now guesses

  • ? Filtered rows, or the whole table?
  • ? Zero rows: an error, an empty file, or nothing?
  • ? Do PII columns go into the file?

The same request as an IntentSpec

intent.md

Every guess, answered on the record

  • ✓ Only the currently filtered rows, never the full dataset.
    anchored to quote · support-ticket-4421
  • ✓ Empty dataset: show the toast, create no file.
    anchored to quote · support-ticket-4421
  • ✓ The output never includes PII fields.
    verification · manual check before merge

Keeping intent explicit, evidence-backed, and upstream of code is Intent Engineering. IntentSpec is the file it travels in.

How it works.

01

Trace the why

Each evidence item names the outcomes and edge cases it justifies. When someone asks why an outcome exists, the file answers.

evidence:
  - type: "quote"
    source: "support-ticket-4421"
    anchors: ["outcome:1"]
02

Define done

Outcomes with observable thresholds, edge cases with expected behavior, verification steps that say how you'll know. Concrete criteria, not a vague prompt.

edgeCases:
  - scenario: "Empty dataset"
    expectedBehavior: "Show toast,
      create no file"
03

Enforce it

The GitHub Action checks the schema on every PR. The CLI grades readiness with a deterministic six-check verdict; when it can't confirm a field, it quotes your text back and flags it instead of guessing.

$ npx -y @pathmode/cli preflight
 
  ✓ goal         ✓ objective
  ✓ outcomes     ✓ constraints
  ✓ edgeCases    ✓ verification
 
✓ Preflight passed. 6/6 checks.
  Ready to hand to an agent.

CI: pathmodeio/validate-intentspec-action@v1

Validate a spec. Right here.

Edit the file on the left. The output runs against the same JSON Schema your CI enforces.

intent.md
Loading schema…output
Loading schema from /intentspec.schema.json…

Uses ajv against /intentspec.schema.json, the same schema the GitHub Action enforces.

Then point your agent at it.

One rule line in the agent's config. The agent reads intent.md before it builds. Works the same in every harness.

CLAUDE.mdmarkdown
Always read intent.md before
implementing any feature.

Frequently asked questions.

What is IntentSpec?
IntentSpec is the portable handoff format for evidence-backed product intent. It's a structured Markdown file with YAML frontmatter that captures what "done" looks like for a feature: objectives, outcomes, edge cases, and the evidence that produced them. Any AI coding agent can read it.
How is IntentSpec different from AGENTS.md or CLAUDE.md?
AGENTS.md and CLAUDE.md provide general repo context. They tell the agent how your codebase is shaped. IntentSpec carries product judgment for a single feature: the outcomes, the edge cases, and the evidence behind the call. One is repo context; the other is per-feature intent.
Do I need Pathmode to use IntentSpec?
No. You can hand-author intent.md files in any text editor, grade them with the free CLI, and validate them in CI. But the value of an IntentSpec is the evidence it carries. Pathmode builds your IntentSpec from your product evidence (quotes, friction, observations) so the handoff to your agent isn't just an opinion someone wrote down.
How does IntentSpec prevent AI agent drift?
Agents drift when specs are vague or unjustified. IntentSpec forces explicit outcomes and edge cases, and the evidence block links each one back to the friction, quote, or observation behind it. The agent has concrete success criteria. The reviewer has the why. Drift loses both arguments.
How is IntentSpec different from spec-driven development tools and GitHub spec-kit?
Spec-driven development tools and spec-kit focus on the contract between spec and implementation: they validate that code conforms to a spec. IntentSpec operates one layer upstream. It carries the evidence that justifies the spec in the first place. The difference is between enforcing "done correctly" and being able to argue why "done" means what it means. IntentSpec is complementary: wire it to spec-kit, reference it from your GH workflows.

Start with the file.

Use the standard. It's free.

Plain Markdown, an open schema, and tooling that runs without an account.

  • → Read the spec
  • → The intent.md profile
  • → Get the GitHub Action
  • $ npx -y @pathmode/cli preflight

Build it from evidence.

Hand-authoring works, and the format never requires a tool. Pathmode generates the IntentSpec from your product evidence: quotes, friction, observations, each anchored to the outcome it justifies.

Build in Pathmode

IntentSpec is an open format stewarded by Pathmode · propose changes on GitHub

Maintained by Janne Lammi. Pathmode builds IntentSpecs from your product evidence.