What is an IntentSpec?
An IntentSpec is a structured document format for capturing product intent. It has five parts:
- Objective — What are we building and why? States the problem, the user segment, and the rationale.
- User Goal — What is the user trying to accomplish? The job-to-be-done, written from the user's perspective.
- Outcomes — What does success look like? Measurable criteria that can be verified programmatically or through testing.
- Edge Cases — What could go wrong? Boundary conditions, error states, and scenarios the implementation must handle.
- Verification — How do we confirm it's done? Specific test cases, acceptance criteria, or automated checks.
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 five 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.
- User Goal prevents scope creep by anchoring every decision to a specific user outcome.
- Outcomes make "done" unambiguous. No debates about whether a feature is complete.
- Edge Cases prevent the agent from making 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 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.