An IntentSpec isn't mainly a document to read — it's product judgment in structured form. Whether you express it in JSON, YAML, or structured English, it must carry these 8 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. (When a constraint holds for every feature, promote it to The Product Constitution instead of retyping it per spec.)
"constraints": [
"No double-charge on retry",
"Must support iOS Safari 15+"
]Scope (What to Touch — and What Not To)
What: The parts of the system the agent may change — and the parts it must leave alone. Why: Keeps the change surgical. "Out of scope" is a fence that stops the agent from refactoring code you never asked it to touch.
"scope": {
"inScope": ["The payment retry path and its error states"],
"outOfScope": ["Cart UI", "Tax calculation", "Saved payment methods"]
}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"
}
]Health Metrics (What Must Not Degrade)
What: What must stay true after the change — the regression guards. Why: Outcomes say what should change; health metrics say what must NOT. Agents optimize for the outcome — name what they could quietly break getting there.
"healthMetrics": [
"Checkout completion rate does not drop",
"Payment page p95 load time stays under 2s"
]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? |
| Scope | What should the agent touch — and leave alone? |
| Edge Cases | What happens when it breaks? |
| Health Metrics | What must NOT degrade? |
| Verification | How do we prove it works? |
Print this out. Tape it to your monitor. Or better yet — make sure your tooling enforces it.