The evidence-backed definition of done.
Your agent knows how to build. intent.md tells it what done means and why, in one file any coding agent can read.
objective:
Make product judgment durable enough to travel with the code.
outcomes:
- - Agents build against observable product outcomes.
- - Assumptions stay visible instead of becoming code.
- - Verification survives the handoff.
schema-valid · readiness 6/6 · free · local · no account
readable by claude-code · cursor · windsurf · copilot · aider · any-llm
the handoff
A spec that can't say why is just an opinion.
The same request, handed off twice.
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: error, empty file, or nothing?
- ?Do PII columns go into the file?
Every guess, answered on the record
- ✓Only the currently filtered rows, never the full dataset.
anchored to friction · support-ticket-4421
- ✓Empty dataset: show the toast, create no file.
anchored to friction · 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
Keep the why attached to done.
01 / trace the why
Evidence names the outcomes and edge cases it justifies. The file answers when someone asks why.
evidence:- type: "friction"source: "support-ticket-4421"anchors: ["outcome:1"]
02 / define done
Observable outcomes, expected edge-case behavior, and checks that make success concrete.
edgeCases:- scenario: "Empty dataset"expectedBehavior: "Show toast,create no file"
03 / enforce it
Grade readiness locally and check the schema on every pull request.
$ npx -y @pathmode/cli preflight
✓ Preflight passed. 6/6 checks.
Ready to hand to an agent.
validate
Validate a spec. Right here.
Edit the file on the left. The output runs against the same JSON Schema your CI enforces.
Uses ajv against /intentspec.schema.json, the same schema the GitHub Action enforces.
use it
Then point your agent at it.
One rule line in the agent's config. It reads intent.md before it builds.
CLAUDE.mdmarkdownAlways read intent.md beforeimplementing any feature.
questions
The short answers.
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 write intent.md in a text editor, run the free CLI, and validate it in CI. Pathmode is an optional connected workspace where the product owner compares an agent proposal with the original request, sends corrections, and authorizes the revised intent. The open format works independently of that service.
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
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
Review the proposal with your team.
In Pathmode, the product owner compares the agent’s proposal with the original request, sends corrections, and authorizes the revision to build. The decision stays in intent.md; private evidence and review history stay in the workspace.
See a review in PathmodeIntentSpec is an open format stewarded by Pathmode · propose changes on GitHub