The 6-Part IntentSpec
An IntentSpec is not a document. It is a data structure. Whether you write it in JSON, YAML, or structured English, it must contain these 6 components to be "Agent-Ready."
Objective (The "Why" & "What")
What: The problem to solve and why it matters. Why: Gives agents the necessary context to make trade-offs when implementation details get tricky.
"objective": "Reduce cart abandonment caused by payment step timeouts exceeding 3 seconds."Outcomes (The Observable State changes)
What: The observable, testable state changes after success. Why: Defines the true "Definition of Done". These aren't tasks, but user-visible states.
"outcomes": [
"Payment completes in under 3s (p95)",
"Users see real-time status during processing",
"Failed payments show actionable error with retry"
]Evidence (The Proof)
What: Linked real user signals (friction points, quotes, metrics). Why: Eliminates solutioneering. If you can't link to actual user evidence, you shouldn't be building it. In Pathmode, these are anchored to specific parts of the spec.
"evidenceIds": ["evd-101", "evd-102"],
"evidenceAnchors": {
"objective": ["evd-101"]
}Constraints (The Guardrails)
What: Hard boundaries—what the agent CANNOT do. Why: Critical for security, architectural integrity, and business rules.
"constraints": [
"No double-charge on retry",
"Must support iOS Safari 15+"
]Edge Cases (The Boundaries)
What: Failure modes and boundary conditions. Why: Happy paths are easy. Agents need to know how to handle the 1% of cases where things go wrong.
"edgeCases": [
{
"scenario": "Network timeout during payment",
"expectedBehavior": "Show retry button, no double-charge"
}
]Verification (The Tests)
What: Concrete tests to confirm success. Why: Don't just let the agent say "done". Force it to prove success code-first.
"verification": {
"e2eTests": ["checkout-payment-retry.spec.ts"]
}The Cheat Sheet
| Component | Question it Answers |
|---|---|
| Objective | Why are we building this? |
| Outcomes | What observable state changes happen? |
| Evidence | What user signals prove this is needed? |
| Constraints | What must we NOT do? |
| Edge Cases | What happens when it breaks? |
| Verification | How do we prove it works? |
Print this out. Tape it to your monitor. Or better yet — make sure your tooling enforces it.