What is an IntentSpec?
An IntentSpec is a structured document format for capturing product intent. It has six parts:
- Objective — What problem are we solving and why does it matter? Grounded in evidence, not assumptions.
- Outcomes — What observable, testable state changes happen when this ships?
- Evidence — What real user signals (friction, quotes, metrics) prove this is needed?
- Constraints — What hard boundaries must the implementation respect?
- Edge Cases — What could go wrong? Boundary conditions, error states, and failure modes.
- 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 six 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 prevents solutioneering — if you can't link to real user signals, you shouldn't be building it.
- Constraints prevent the agent from making incompatible or unsafe choices.
- Edge Cases prevent naive assumptions about happy-path-only behavior.
- Verification closes the loop — the spec defines its own test criteria.
Remove any one part and the spec becomes fragile. Without evidence, you're building on assumptions. Without edge cases, agents produce code that breaks on real-world input. Without verification, there's no way to confirm the intent was met.
How agents consume it
IntentSpecs are designed for machine readability. In Pathmode, specs can be exported as MCP context (delivered to Claude Code or Cursor via the Model Context Protocol) or as .cursorrules / CLAUDE.md files that the agent reads at session start.
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.
- User Goal: Regain account access within 2 minutes without contacting support.
- Outcomes: Reset email delivered within 10 seconds; link expires after 1 hour; password updated on first valid submission.
- 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.
- 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 gives an AI agent everything it needs to implement, test, and verify — without a single follow-up question.