What is an IntentSpec?
An IntentSpec is a structured document format for capturing product intent. It has eight parts:
- Objective — What problem are we solving and why does it matter? Make the reasoning and any assumptions explicit.
- Outcomes — What observable, testable state changes happen when this ships?
- Evidence — What user signals (friction, quotes, metrics) support or challenge the claims, when available?
- Constraints — What hard boundaries must the implementation respect?
- Scope — What may the implementation touch, and what must it leave alone?
- Edge Cases — What could go wrong? Boundary conditions, error states, and failure modes.
- Health Metrics — What must NOT degrade as a result of this change?
- Verification — How do we confirm it works? Specific tests and acceptance criteria.
This format is intentionally compact. A good IntentSpec fits in a single screen. It avoids the bloat of traditional PRDs while adding the precision that AI agents require.
Why eight parts?
Each part serves a distinct function in the execution chain:
- Objective gives the agent (or engineer) enough context to make judgment calls when the spec doesn't cover a scenario.
- Outcomes make "done" unambiguous. No debates about whether a feature is complete.
- Evidence helps the team judge the proposal. Link signals to the claims they support and keep unreviewed signals and assumptions visible.
- Constraints prevent the agent from making incompatible or unsafe choices.
- Scope keeps the change surgical — it fences off the code the agent must not touch.
- Edge Cases prevent naive assumptions about happy-path-only behavior.
- Health Metrics name what must not regress, so the agent doesn't quietly break one thing while fixing another.
- Verification closes the loop — the spec defines its own test criteria.
These parts help expose gaps before implementation. A proposal can reach review and authorization without evidence; missing backing remains visible so a person can decide whether to proceed. Evidence coverage is not a readiness gate, and passing preflight does not authorize implementation. Edge cases and verification still need concrete answers so the team can judge what will happen and how to check it.
How agents consume it
IntentSpecs are designed for human review and machine readability. The repository's intent.md is the implementation authority. A connected Pathmode workspace holds private evidence, corrections, and authorization of the reviewed revision. Agents read the file and retrieve that connected context through MCP. Optional exports include AGENTS.md, CLAUDE.md, and .cursorrules.
The structured format means agents don't need to parse narrative text looking for requirements. Each section maps directly to an execution concern: what to build, for whom, what success looks like, what to watch out for, and how to verify.
Compared to a Jira ticket
A Jira ticket says: "As a user, I want to reset my password so that I can regain access to my account."
An IntentSpec says:
- Objective: Users who forget their password currently have no self-service recovery — they email support, creating a 24-hour delay and 15% churn at this step.
- Outcomes: Reset email delivered within 10 seconds; link expires after 1 hour; password updated on first valid submission; users regain access in under 2 minutes without contacting support.
- Edge Cases: Expired link shows clear message with re-send option; rate-limited to 3 requests per hour per email; works with SSO-linked accounts.
- Health Metrics: Login success rate for existing users does not drop; support ticket volume for account access falls.
- Verification: E2E test covers happy path, expired link, and rate limit. Monitoring alert if delivery p95 exceeds 30 seconds.
The difference is precision. The IntentSpec makes the proposed behavior inspectable before implementation. If the agent discovers a contradiction or an unanswered product choice, it brings that back for review rather than guessing.