The Anatomy of an Agent-Ready Spec
Most specifications are written for humans. They're prose-heavy, ambiguous, and rely on "common sense" that AI agents don't have. An Agent-Ready Spec is different. It's structured, explicit, and machine-readable.
This guide breaks down the core components.
Why Structure Matters
When you hand a coding agent a Jira ticket that says:
"Add a login button to the header"
The agent has to guess:
- Where in the header?
- What does login mean? Email/password? OAuth?
- What happens after login? Redirect?
- What does the button look like?
An Agent-Ready Spec answers these questions before the agent starts writing code.
The Core Components
1. Intent ID & Traceability
Every spec should have a unique ID and link back to the user evidence that created it.
{
"intentId": "INT-2026-0042",
"source": {
"type": "friction",
"frictionId": "FRC-1023",
"evidence": "User interview: 'I couldn't find where to log in.'"
}
}Why it matters: When the agent writes code, it can add comments like // Implements INT-2026-0042. This creates a traceable line from user pain to shipped code.
2. Behavior Definition (What, Not How)
Describe the desired outcome, not the implementation.
{
"behavior": {
"userStory": "As a visitor, I can sign in to access my dashboard.",
"acceptanceCriteria": [
"A 'Sign In' button is visible in the header.",
"Clicking the button opens a modal with email/password fields.",
"Successful login redirects the user to /dashboard.",
"Invalid credentials display an error message."
]
}
}Why it matters: This gives the agent clear success criteria without dictating how to build it. The agent can choose the best implementation.
3. Context & Constraints
Provide the environmental context the agent needs.
{
"context": {
"component": "Header.tsx",
"framework": "Next.js 15",
"designSystem": "Tailwind CSS",
"authProvider": "Supabase Auth"
},
"constraints": [
"Must not break existing navigation links.",
"Button style must match existing 'Get Started' button."
]
}Why it matters: This prevents the agent from making incompatible choices. It knows the tech stack and the guardrails.
4. Verification Hooks
Tell the agent how to verify its own work.
{
"verification": {
"e2eTests": [
"User can complete full sign-in flow."
],
"unitTests": [
"Auth service returns correct error codes."
],
"manualChecks": [
"Visually inspect button placement on mobile."
]
}
}Why it matters: This enables autonomous agents to self-verify before asking for human review.
Putting It Together
A complete Agent-Ready Spec might look like this:
{
"intentId": "INT-2026-0042",
"source": {
"type": "friction",
"frictionId": "FRC-1023",
"evidence": "User interview: 'I couldn't find where to log in.'"
},
"behavior": {
"userStory": "As a visitor, I can sign in to access my dashboard.",
"acceptanceCriteria": [
"A 'Sign In' button is visible in the header.",
"Clicking the button opens a modal with email/password fields.",
"Successful login redirects the user to /dashboard.",
"Invalid credentials display an error message."
]
},
"context": {
"component": "Header.tsx",
"framework": "Next.js 15",
"designSystem": "Tailwind CSS",
"authProvider": "Supabase Auth"
},
"constraints": [
"Must not break existing navigation links.",
"Button style must match existing 'Get Started' button."
],
"verification": {
"e2eTests": [
"User can complete full sign-in flow."
],
"unitTests": [
"Auth service returns correct error codes."
],
"manualChecks": [
"Visually inspect button placement on mobile."
]
}
}This is not a document. This is an API payload.
Next Steps
Now that you understand the anatomy, try creating your first Agent-Ready Spec in Pathmode. Connect your friction sources, and let Pathmode synthesize the initial specification for you.