Evidence-backed intent,
compiled for any coding agent.

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 compile it from your product judgment.

intent.md

---
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"
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"
---

Try it: validate a spec

Edit the spec on the left. It's validated against the same JSON Schema your CI uses.

intent.md

---
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"
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"
---

Loading schema…

Loading schema from /intentspec.schema.json…

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

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, compiled

IntentSpec carries the why alongside the what. Outcomes anchor to quotes, friction, and observations. Agents execute against the contract. Humans review against the evidence that produced it.

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

Point your AI agent to it

Reference the spec in your agent's context. One line is all it takes — the agent now knows exactly what "Done" means.

# CLAUDE.md or .cursor/rules

Read intent.md before
implementing any feature.

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

How it differs from what you already use

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.

Drop it into any agent

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

Claude Code

CLAUDE.md

Always read intent.md before
implementing any feature.

Cursor

.cursor/rules/intentspec.mdc

---
description: IntentSpec
alwaysApply: true
---
Read intent.md before generating code.

Windsurf

.windsurfrules

Read intent.md before
implementing any feature.

GitHub Copilot

.github/copilot-instructions.md

Reference intent.md for
feature requirements.

Aider

CONVENTIONS.md

$ aider --read intent.md

Any LLM

System prompt

Treat the attached intent.md
as the source of truth for "done".

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 — including 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 compiles 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.

Specs in the wild

Real intent.md files from real repositories — compiled from evidence or hand-authored, validated in CI, consumed by AI agents.

T3 Stack Showcase

Full-stack Todo feature with TRPC + Zod + Tailwind

GitHub →

---
id: "showcase-todo-feature"
status: "approved"
objective: "Implement a full-stack Todo
  feature with persistence"
outcomes:
  - "User can create a Todo item"
  - "User can toggle completion status"
  - "User can delete a Todo item"
  - "All changes persist via TRPC"
constraints:
  - "Must use TRPC for all API calls"
  - "Must use Zod for input validation"
  - "Must use Tailwind for styling"
---

Submit your spec

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

Open an issue →

Start with evidence

Hand-author your first IntentSpec. Or compile one from your product evidence in Pathmode.

Get the GitHub Action Compile in Pathmode JSON Schema

Evidence-backed intent,
compiled for any coding agent.

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 compile it from your product judgment.

intent.md

---
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"
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"
---

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

Point your AI agent to it

Reference the spec in your agent's context. One line is all it takes — the agent now knows exactly what "Done" means.

# CLAUDE.md or .cursor/rules

Read intent.md before
implementing any feature.

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

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?

--- id: "showcase-todo-feature" status: "approved" objective: "Implement a full-stack Todo feature with persistence" outcomes: - "User can create a Todo item" - "User can toggle completion status" - "User can delete a Todo item" - "All changes persist via TRPC" constraints: - "Must use TRPC for all API calls" - "Must use Zod for input validation" - "Must use Tailwind for styling" ---

Evidence-backed intent,compiled for any coding agent.

Try it: validate a spec

The problem: specs without evidence

The solution: judgment, compiled

How It Works

Write an intent.md

Point your AI agent to it

Validate in CI

How it differs from what you already use

Drop it into any agent

Claude Code

Cursor

Windsurf

GitHub Copilot

Aider

Any LLM

Frequently Asked Questions

Specs in the wild

T3 Stack Showcase

Submit your spec

Start with evidence

Evidence-backed intent,compiled for any coding agent.

Try it: validate a spec

The problem: specs without evidence

The solution: judgment, compiled

How It Works

Write an intent.md

Point your AI agent to it

Validate in CI

How it differs from what you already use

Drop it into any agent

Claude Code

Cursor

Windsurf

GitHub Copilot

Aider

Any LLM

Frequently Asked Questions

Specs in the wild

T3 Stack Showcase

Submit your spec

Start with evidence

Evidence-backed intent,
compiled for any coding agent.

Evidence-backed intent,
compiled for any coding agent.