The 5-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 5 components to be "Agent-Ready."
Intent ID (The Handle)
What: A unique identifier for traceability.
Why: Allows agents to tag their commits (feat: implement INT-101) and links code back to user friction.
"intentId": "INT-2026-042"Source (The Trace)
What: The evidence that proves this needs to exist. Why: Prevents "solutioneering." If you can't link to a friction point, you shouldn't be building it.
"source": {
"type": "friction",
"frictionId": "FRC-881",
"quote": "I can't find the export button."
}Behavior (The Contract)
What: The user story and acceptance criteria. Why: Defines the "Definition of Done." This is the contract the agent must fulfill.
"behavior": {
"userGoal": "As a user, I can export data to CSV.",
"outcomes": [
"Export button visible on Data tab",
"Clicking triggers CSV download",
"Filename is date-stamped"
]
}Context (The Injection)
What: The environment the agent is working in. Why: Prevents hallucinations. Tells the agent where to write code and what tools to use.
"context": {
"file": "components/DataGrid.tsx",
"framework": "React/Next.js",
"designSystem": "Tailwind UI"
}Constraints (The Guardrails)
What: The "DO NOT" list. Why: Critical for security, performance, and brand consistency.
"constraints": [
"Do not expose user emails in the CSV",
"Max 1000 rows per export"
]The Cheat Sheet
| Component | Question it Answers |
|---|---|
| Intent ID | What do we call this? |
| Source | Why are we building this? |
| Behavior | What does success look like? |
| Context | Where does this live? |
| Constraints | What must we avoid? |
Print this out. Tape it to your monitor. Or better yet—make sure your tooling enforces it.