IntentSpec:
The Open Standard for
Spec-Driven Development.

Functional Guardrails for your AI Agents. Prevent architectural drift, wrong dependencies, and hallucinated APIs.

intent.md

---
id: "INT-EXPORT-JSON-001"
status: "approved"
objective: "Allow users to export filtered data to JSON"
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

Loading schema…

Loading schema from /intentspec.schema.json…

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

The Problem: Probabilistic Engineering

You prompt an agent. It works. Two weeks later, another developer prompts it differently, and it breaks. "Vibe coding" is not engineering. Prompts are ephemeral; they don't survive context switching.

The Solution: Functional Guardrails

IntentSpecis a structured contract that lives in your repo. It tells any agent (Cursor, Windsurf, Augment) exactly what "Done" looks like before it writes a single line of code.

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 are machine-validatable contracts for AI agents.

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

One rule line in your agent's config tells it to read intent.md before writing code.

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 an open standard for spec-driven development. It's a structured Markdown file with YAML frontmatter that defines what "done" looks like for a feature — including objectives, expected outcomes, constraints, edge cases, and health metrics. Any AI coding agent can consume it.

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

AGENTS.md and CLAUDE.md are unstructured text files that provide general context to AI agents. IntentSpec is a schema-validated, machine-readable specification that defines specific feature requirements with testable outcomes and constraints. It's enforceable in CI/CD, not just advisory.

Which AI coding agents work with IntentSpec?

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

Do I need Pathmode to use IntentSpec?

No. IntentSpec is an open standard. You can write intent.md files by hand in any text editor and commit them to your repo. Pathmode provides a visual editor and team workflow for creating IntentSpecs, but it's not required.

Can IntentSpec be validated automatically?

Yes. IntentSpec includes a formal JSON Schema and a GitHub Action (validate-intentspec-action) that checks your specs on every pull request. This prevents malformed or incomplete specs from reaching your main branch.

How does IntentSpec prevent AI agent drift?

AI agents hallucinate when specs are vague. IntentSpec forces you to define explicit outcomes, constraints, and edge cases before coding begins. The agent has concrete success criteria instead of ambiguous instructions, which dramatically reduces drift and rework.

Specs in the wild

Real intent.md files from real repositories — written by hand, 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 Specifying Today

You can write IntentSpecs by hand, or use the visual editor reference implementation.

Get the GitHub Action Open Visual Editor JSON Schema

IntentSpec:
The Open Standard for
Spec-Driven Development.

Functional Guardrails for your AI Agents. Prevent architectural drift, wrong dependencies, and hallucinated APIs.

intent.md

---
id: "INT-EXPORT-JSON-001"
status: "approved"
objective: "Allow users to export filtered data to JSON"
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

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?

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

IntentSpec:The Open Standard forSpec-Driven Development.

Try it: validate a spec

The Problem: Probabilistic Engineering

The Solution: Functional Guardrails

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 Specifying Today

IntentSpec:The Open Standard forSpec-Driven Development.

Try it: validate a spec

The Problem: Probabilistic Engineering

The Solution: Functional Guardrails

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 Specifying Today

IntentSpec:
The Open Standard for
Spec-Driven Development.

IntentSpec:
The Open Standard for
Spec-Driven Development.