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? 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?
- 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 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.
- 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.
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.
- 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 gives an AI agent everything it needs to implement, test, and verify — without a single follow-up question.