Keep private evidence private. profile 1.0
The repo-safe profile keeps summaries and references in the file. Raw customer material stays in a protected source.
Skip to contentBuild what
Less room for guessing.
One file.
Try the format.
An open format.
Your next change starts
IntentSpec · open standard · MIT
Build what
you meant.
An open format for evidence-backed product intent.
Give your coding agent the problem, the boundaries, and what success looks like. Keep it in intent.md, beside your code.
$npx -y @pathmode/cli preflightDownload the example. Check it locally. No account needed.
Same repo. Different question.AGENTS.md tells your agent how to work.intent.md tells it what this change is for.
A SMALL FILE. A SHARED UNDERSTANDING.01 / EXAMPLE
intent.md
Export the rows I am looking at as JSON
Analysts take filtered results into their own tools without filing a support ticket.
What must be true
- Export never contains rows outside the active filter.outcome:0
- The file never includes PII fields.outcome:1
The boundary
Runs client-side. No new export endpoint.
If things go sideways
Empty dataset
Show a toast, create no file.
How we'll check
Unit test asserts PII columns are stripped.
↗ The reason behind itsupport-ticket-4421
Analysts re-filter full exports by hand.
Linked to outcome:0 ↗edgeCase:0 ↗
---id: json-exportstatus: approveduserGoal: Export the rows I am looking at as JSONobjective: >- Analysts take filtered results into their own tools without filing a support ticket.outcomes: - Export never contains rows outside the active filter. - The file never includes PII fields.constraints: - Runs client-side. No new export endpoint.edgeCases: - scenario: Empty dataset expectedBehavior: Show a toast, create no file.verification: - Unit test asserts PII columns are stripped.evidence: - type: friction source: support-ticket-4421 excerpt: Analysts re-filter full exports by hand. anchors: ["outcome:0", "edgeCase:0"]---
One example, two views. Evidence uses a summary and source reference.See what changed ↓
Using the intent.md format from Anthropic’s AI-native SDLC playbook? See a worked preflight check ↗
Readable by peoplePlain Markdown. Review it like a document.
Versioned with your codeThe why travels with the change.
Checkable by toolsOpen schema. Deterministic preflight.
01 DEFINE THE OUTCOME
Less room for guessing.
More room for getting it right.
“Add an export” leaves the important decisions open. A useful intent names the behavior you can actually check.
⊘ A task to interpretoutcomes · before
“Add JSON export.”“Make exports easy to use.”
Preflight: outcomes unconfirmed.
These lines name an activity and a preference. They leave the rows, the contents, and the expected behavior open.
✓ An outcome to build towardoutcomes · after
“Export never contains rows outside the active filter.”“The file never includes PII fields.”
Preflight: outcomes pass.
Two explicit boundaries. Each can be checked independently against the exported file.
Checked with CLI 2.7.0. Only the outcomes changed; the rest of the example is identical.Download the before file ↗
↗ Keep the why attached.
Link the support signal to the outcome it explains. The next person can follow the decision back to its source.
⌁ Make the limits explicit.
Constraints say what cannot change. Edge cases say what happens when the happy path ends.
✓ Name the proof.
Record how you'll check the result. Passing a readiness check is the start; verifying the build comes next.
02 PUT IT TO WORK
One file.
Your existing workflow.
Keep the editor, agent, and repository you already use. Add the intent alongside them.
Start with a concrete example.
Save
Download the JSON export example ↓intent.mdin your repository. Replace the example with your problem, outcomes, and boundaries; set its status todraftwhile you refine it.Check it before the agent builds.
Run preflight in the same directory. It reads the file locally, reports what it cannot confirm, and exits nonzero when a gate blocks.
Point your agent at the file.
Add this instruction to the rules your agent already reads.
AGENTS.mdRead intent.md before implementing this change. Check the result against its outcomes and constraints.
$ npx -y @pathmode/cli preflight- ✓ goal
- ✓ constraints
- ✓ objective
- ✓ edgeCases
- ✓ outcomes
- ✓ verification
✓ Preflight passed. 6/6 checks.Ready to hand to an agent.
Output excerpt from this example · CLI 2.7.0
Runs locally · no account or API key
Runs locally · no account or API key
Readiness is one check. Correctness is another. Preflight checks six dimensions using fixed rules. It can miss valid phrasing, and a pass does not prove the product decision or implementation is right.
Add schema validation to your pull requests03 CHECK YOUR FILE
Try the format.
See what holds up.
Edit the example or paste your own intent.md. Schema and readiness checks run in your browser; your text stays on this page.
Checks update as you type
CHECK RESULT
Loading the validator…
The example is available to download while the checker loads.
Try changing outcomes: to a string, or changing edgeCase:0 to edgeCase:9.
Compare the two examples
A valid format can still describe a vague outcome. Both examples pass the schema. The before file fails readiness on outcomes; the after file passes all six gates.
These checks do not approve a change, verify an implementation, or audit private information.
A FEW GOOD QUESTIONS
Before you start.
The details behind a very small file.
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.
Compare intent.md with AGENTS.md, Spec Kit, OpenSpec and Kiro ↗
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 manager 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 requires explicit outcomes and supports edge cases and evidence linked to the requirements they justify. Readiness checks help identify gaps; human review and authorization establish whether the agent should proceed.
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.
Compare intent.md with AGENTS.md, Spec Kit, OpenSpec and Kiro ↗
What does a passing preflight actually mean?
The deterministic checks confirmed the goal, objective, outcomes, constraints, edge cases, and verification in the text. These checks use a fixed vocabulary and can miss valid wording. A pass does not establish that the product decision is good, grant approval, or verify the implementation.
What evidence is safe to commit?
Use summaries and references, with raw customer quotes, personal identifiers, confidential metrics, and secrets kept out of the repository. A summary still needs review for sensitive information.
Read the repo-safe profile ↗
BUILT TO BE SHARED
An open format.
A file you own.
IntentSpec defines what the file means. The schema checks its structure; the shared conformance cases let tool builders check that they read it consistently.
Use it with any agent. Build your own tools around it. The specification and schema are available under MIT.
MIT LICENSEFORMAT v1.2NO ACCOUNT REQUIRED
A small format, evolving in public.
Changelog ↗Define the scope. Name the checks. v1.2
Optional scope and verification fields make the permission boundary and feedback loop explicit.
Connect the signal to the spec. v1.1
Typed evidence and anchors connect a source to the part of the intent it supports.
Your next change starts
with a shared understanding.
Put the intent beside the code. Give your agent something clear to build from.
Get intent.md Plain Markdown. Yours to change.