Open format · Schema-validated · v1.2

your-repo/intent.md

Evidence-backed intent, ready for any coding agent.

Not just another prompt. IntentSpec is the open format for the work upstream of code: the outcomes, edge cases, and evidence that define done. Write it by hand, or let Pathmode build it from your product evidence.

Read the spec Validate a spec [V]

intent.mdyaml

---
id: "INT-EXPORT-JSON-001"
status: "approved"
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."
    anchors: ["outcome:0", "edgeCase:0"]
  - type: "friction"
    source: "session-replay-a3f9"
    excerpt: "User re-exported full dataset 3 times trying to find filtered subset."
    anchors: ["objective"]
outcomes:
  - "User clicks Export → JSON file downloads to device"
  - "Export contains only the currently filtered dataset"
  - "No PII fields are included in the output"
constraints:
  - "Must run client-side only (no server round-trip)"
  - "File size must not exceed 10MB"
scope:
  inScope:
    - "The export button and its filtered-data serializer"
  outOfScope:
    - "The filter UI"
    - "Saved-view persistence"
edgeCases:
  - scenario: "Empty dataset"
    expectedBehavior: "Show toast: 'Nothing to export' — no file created"
  - scenario: "10k+ rows"
    expectedBehavior: "Stream to file, show progress indicator"
healthMetrics:
  - "Page load time must not increase"
  - "Existing CSV export must continue to work"
verification:
  - "Unit test: serializer emits only filtered rows, no PII keys"
  - "Manual: export with 0 rows shows the toast, writes no file"
  - "Prod signal: export error rate < 0.5% after launch"
---

anchors:Each evidence item names the outcomes and edge cases it justifies, so the agent knows why each outcome exists, not just what it is. One spec. One artifact. No separate design doc to hand off.

Full spec →

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

Validate a spec. Right here.

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

intent.md

---
id: "INT-EXPORT-JSON-001"
status: "approved"
userGoal: "Export filtered data to JSON"
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."
    anchors: ["outcome:0", "edgeCase:0"]
  - type: "friction"
    source: "session-replay-a3f9"
    excerpt: "User re-exported full dataset 3 times trying to find filtered subset."
    anchors: ["objective"]
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"
constraints:
  - "Must run client-side only (no server round-trip)"
  - "File size must not exceed 10MB"
edgeCases:
  - scenario: "Empty dataset"
    expectedBehavior: "Show toast: 'Nothing to export' — no file created"
  - scenario: "10k+ rows"
    expectedBehavior: "Stream to file, show progress indicator"
verification:
  - "Unit test: exporting a filtered 100-row set yields exactly those rows"
  - "Manual: apply a filter, export, confirm the file has no PII columns"
  - "Shipped signal: repeat-export rate per session drops"
healthMetrics:
  - "Page load time must not increase"
  - "Existing CSV export must continue to work"
---

Loading schema…output

Loading schema from /intentspec.schema.json…

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

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

The problem: specs without evidence

A spec that doesn't trace back to evidence is just opinion. When the agent asks "why this outcome?", the answer is "because someone said so." That's how scope creeps, agents drift, and PRs get rejected after the work is done.

The solution: judgment, carried

Intent is judgment under evidence, not a contract you compile from a prompt. That's Intent Engineering. IntentSpec is the form that judgment takes: outcomes anchored to quotes, friction, and observations, validated in CI like any spec. The evidence-anchored why and the machine-checkable spec are one artifact, not two. Agents execute against it; humans review against the evidence that produced it.

Make every outcome trace back.

Evidence flows in. A spec flows out. The anchors field ties each outcome, edge case, and constraint to the signal that justified it.

quote"I don’t want another password."frictionRe-exported the full dataset 3 timesobservationUsers skip the empty statemetricExport error rate 4.1%request"Let me pick the columns."quote"I can’t tell what’s in my export."frictionSetting resets after dark-mode toggleobservationRetries the upload after every timeout

anchors: evidence → outcome

objectiveoutcome:0outcome:1edgeCase:0constraint:1outcome:2edgeCase:1verificationhealthMetricsscope.outOfScopestatus: approved

Intent Engineering

The practice of maintaining explicit, evidence-backed product intent upstream of code, so agents have concrete criteria for done instead of vague requirements that get interpreted differently every sprint. IntentSpec is the portable format that carries that intent from discovery to deployment.

How it works.

Three steps to go from vibe coding to spec-driven development.

Write an intent.md

Define the objective, expected outcomes, constraints, and edge cases in a Markdown file with YAML frontmatter. Commit it alongside your code.

your-repo/
├── src/
├── intent.md   ← your spec
└── package.json

Drop it into any agent

One rule line in your agent's config file points at intent.md. The agent now has concrete success criteria, not a vague prompt.

Works with Claude Code, Cursor, Windsurf, GitHub Copilot, Aider, and any LLM. See the config snippets below.

Validate in CI

Add the GitHub Action to enforce schema compliance on every PR. Prevent drift before it reaches main.

- uses: JanneL/validate-
    intentspec-action@v1
  with:
    file: intent.md

Enforced in CI.

The GitHub Action checks every pull request against the schema. A malformed or evidence-free spec never reaches main.

checksbash

$ git push origin feature/export-json
 
run  JanneL/validate-intentspec-action@v1
     with: file: intent.md
 
✓ frontmatter parsed
✓ conforms to intentspec.schema.json · v1.2
✓ evidence anchors resolve (outcome:0, edgeCase:0)
 
check passed · intent.md is a valid IntentSpec

validate-intentspec-action on the GitHub Marketplace.

Drop it into any agent.

Hand-author intent.md, or build it from your evidence in Pathmode. Either way, one rule line in your agent's config points at it.

CLAUDE.mdmarkdown

Always read intent.md before
implementing any feature.

Not a ticket. Not a rule file.

Tickets, agent rule files, and design docs all describe work, but none of them carry evidence in a form an AI agent can read.

	Linear / Jira ticket	AGENTS.md / .cursorrules	RFC / design doc	IntentSpec
Format	Free-form fields	Free-form Markdown	Prose	Markdown + YAML + JSON Schema
Machine-validated	No	No	No	Yes
Enforceable in CI	No	No	No	Yes
Defines "Done"	Sometimes	No	Sometimes	Always
Carries evidence	No	No	Sometimes	Yes
Designed for AI agents	No	Yes	No	Yes
Scope	Per-task	Per-repo	Per-system	Per-feature

IntentSpec is complementary, not a replacement. Link from your ticket, reference from your AGENTS.md, derive from your RFC.

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.

Which AI coding agents work with IntentSpec?

IntentSpec works with any coding agent that can read context files: Claude Code, Cursor, Windsurf, Augment, GitHub Copilot, Aider. It's Markdown with structured frontmatter, so there's no proprietary lock-in.

Do I need Pathmode to use IntentSpec?

No. You can hand-author intent.md files in any text editor 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.

Can IntentSpec be validated automatically?

Yes. IntentSpec ships with a JSON Schema and a GitHub Action (validate-intentspec-action) that checks specs on every pull request. Malformed or incomplete specs are caught before they reach main.

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.

Specs in the wild.

Real intent.md files: built from evidence or hand-authored, validated in CI, consumed by AI agents.

T3 Stack Showcase

Full-stack Todo · TRPC + Zod + Tailwind

GitHub →

---
id: "showcase-todo-feature"
status: "approved"
objective: "Full-stack Todo with
  TRPC + Zod + Tailwind"
evidence:
  - type: "friction"
    source: "user-feedback-q3"
    excerpt: "Todos disappear on
      refresh — users expect
      persistence."
    anchors: ["outcome:3"]
outcomes:
  - "User can create a Todo item"
  - "User can toggle completion"
  - "User can delete a Todo item"
  - "All changes persist via TRPC"
constraints:
  - "Must use TRPC for all API calls"
  - "Must use Zod for validation"
---

GitHub OAuth

Hand-authored alongside existing email auth

---
id: "INT-AUTH-OAUTH-003"
status: "approved"
objective: "Add GitHub OAuth as
  a sign-in option"
evidence:
  - type: "quote"
    source: "beta-feedback-nov"
    excerpt: "I'd use this but I
      don't want another password."
    anchors: ["objective",
      "outcome:0"]
outcomes:
  - "User can sign in with GitHub
    in one click"
  - "Existing users can link
    their account"
edgeCases:
  - scenario: "GitHub email matches
      existing account"
    expectedBehavior: "Prompt to
      link — never auto-merge"
---

Submit your spec

Open a PR with your intent.md to add your repo to the gallery.

Open an issue →

Start with evidence.

Read the spec, add the GitHub Action, or build your first IntentSpec from product evidence in Pathmode.

Read the spec Get the GitHub Action Build in Pathmode

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

your-repo/intent.md

Evidence-backed intent, ready for any coding agent.

intent.mdyaml

---
id: "INT-EXPORT-JSON-001"
status: "approved"
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."
    anchors: ["outcome:0", "edgeCase:0"]
  - type: "friction"
    source: "session-replay-a3f9"
    excerpt: "User re-exported full dataset 3 times trying to find filtered subset."
    anchors: ["objective"]
outcomes:
  - "User clicks Export → JSON file downloads to device"
  - "Export contains only the currently filtered dataset"
  - "No PII fields are included in the output"
constraints:
  - "Must run client-side only (no server round-trip)"
  - "File size must not exceed 10MB"
scope:
  inScope:
    - "The export button and its filtered-data serializer"
  outOfScope:
    - "The filter UI"
    - "Saved-view persistence"
edgeCases:
  - scenario: "Empty dataset"
    expectedBehavior: "Show toast: 'Nothing to export' — no file created"
  - scenario: "10k+ rows"
    expectedBehavior: "Stream to file, show progress indicator"
healthMetrics:
  - "Page load time must not increase"
  - "Existing CSV export must continue to work"
verification:
  - "Unit test: serializer emits only filtered rows, no PII keys"
  - "Manual: export with 0 rows shows the toast, writes no file"
  - "Prod signal: export error rate < 0.5% after launch"
---

Full spec →

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

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

The problem: specs without evidence

The solution: judgment, carried

How it works.

Three steps to go from vibe coding to spec-driven development.

Write an intent.md

Define the objective, expected outcomes, constraints, and edge cases in a Markdown file with YAML frontmatter. Commit it alongside your code.

your-repo/
├── src/
├── intent.md   ← your spec
└── package.json

Drop it into any agent

One rule line in your agent's config file points at intent.md. The agent now has concrete success criteria, not a vague prompt.

Works with Claude Code, Cursor, Windsurf, GitHub Copilot, Aider, and any LLM. See the config snippets below.

Validate in CI

Add the GitHub Action to enforce schema compliance on every PR. Prevent drift before it reaches main.

- uses: JanneL/validate-
    intentspec-action@v1
  with:
    file: intent.md

$ git push origin feature/export-json

run JanneL/validate-intentspec-action@v1

with: file: intent.md

✓ frontmatter parsed

✓ conforms to intentspec.schema.json · v1.2

✓ evidence anchors resolve (outcome:0, edgeCase:0)

check passed · intent.md is a valid IntentSpec

Linear / Jira ticket

AGENTS.md / .cursorrules

RFC / design doc

IntentSpec

Format

Free-form fields

Free-form Markdown

Prose

Markdown + YAML + JSON Schema

Machine-validated

Yes

Enforceable in CI

Yes

Defines "Done"

Sometimes

Always

Carries evidence

Sometimes

Yes

Designed for AI agents

Yes

Scope

Per-task

Per-repo

Per-system

Per-feature

Frequently asked questions.

What is IntentSpec?

How is IntentSpec different from AGENTS.md or CLAUDE.md?

Which AI coding agents work with IntentSpec?

Do I need Pathmode to use IntentSpec?

Can IntentSpec be validated automatically?

Yes. IntentSpec ships with a JSON Schema and a GitHub Action (validate-intentspec-action) that checks specs on every pull request. Malformed or incomplete specs are caught before they reach main.

How does IntentSpec prevent AI agent drift?

How is IntentSpec different from spec-driven development tools and GitHub spec-kit?

---

id: "showcase-todo-feature"

status: "approved"

objective: "Full-stack Todo with

TRPC + Zod + Tailwind"

evidence:

- type: "friction"

source: "user-feedback-q3"

excerpt: "Todos disappear on

refresh — users expect

persistence."

anchors: ["outcome:3"]

outcomes:

- "User can create a Todo item"

- "User can toggle completion"

- "User can delete a Todo item"

- "All changes persist via TRPC"

constraints:

- "Must use TRPC for all API calls"

- "Must use Zod for validation"

---

id: "INT-AUTH-OAUTH-003"

status: "approved"

objective: "Add GitHub OAuth as

a sign-in option"

evidence:

- type: "quote"

source: "beta-feedback-nov"

excerpt: "I'd use this but I

don't want another password."

anchors: ["objective",

"outcome:0"]

outcomes:

- "User can sign in with GitHub

in one click"

- "Existing users can link

their account"

edgeCases:

- scenario: "GitHub email matches

existing account"

expectedBehavior: "Prompt to

link — never auto-merge"

---