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:

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. Objective

Every spec starts with the problem — not the solution. The objective explains what user problem you're solving and why it matters.

{
  "objective": "Users can't find where to log in — 23% of new visitors bounce from the homepage without attempting sign-in, evidenced by 4 friction reports and analytics drop-off data."
}

Why it matters: When the agent encounters ambiguity during implementation, a clear objective lets it make the right trade-off. Without it, the agent optimizes for the wrong thing.

2. Outcomes

Outcomes are the observable, testable state changes that define "done." Not tasks — states.

{
  "outcomes": [
    "A 'Sign In' button is visible in the header on all pages.",
    "Clicking the button opens a modal with email/password fields.",
    "Successful login redirects the user to /dashboard.",
    "Invalid credentials display an inline error: 'Invalid email or password.'"
  ]
}

Why it matters: Outcomes give the agent a concrete checklist. No guessing whether "login flow" includes a loading state, error handling, or redirect. It's all explicit.

3. Evidence

Link to the real user signals that justify building this. Evidence prevents solutioneering — if you can't trace back to user data, you shouldn't be building it.

{
  "evidenceIds": ["evd-1023", "evd-1024"],
  "evidenceAnchors": {
    "objective": ["evd-1023"],
    "outcome:0": ["evd-1024"]
  }
}

Why it matters: Evidence anchoring creates a traceable line from user pain to shipped code. When the agent writes code, it can reference // Addresses friction evd-1023. When you review the spec later, you can verify it still solves the original problem.

4. Constraints

Hard boundaries — what the agent must NOT do.

{
  "constraints": [
    "Must not break existing navigation links.",
    "Button style must match existing 'Get Started' button.",
    "Passwords must never be logged or stored in plaintext.",
    "Must use existing AuthContext for state management."
  ]
}

Why it matters: Agents operate in isolation. They don't know your team's conventions, security requirements, or architectural decisions unless you tell them. Constraints prevent technically correct but contextually wrong code.

5. Edge Cases

Happy paths are easy. Edge cases define what happens when things go wrong.

{
  "edgeCases": [
    {
      "scenario": "User submits with an unverified email",
      "expectedBehavior": "Show 'Email not verified' error with a resend link"
    },
    {
      "scenario": "Auth provider is down",
      "expectedBehavior": "Show generic error, do not expose provider details"
    }
  ]
}

Why it matters: Every unhandled edge case is a potential hallucination point. The agent will make something up for unspecified scenarios — and it probably won't be what you want.

6. Verification

Tell the agent how to prove its own work.

{
  "verification": {
    "e2eTests": [
      "login-flow.spec.ts"
    ],
    "unitTests": [
      "auth-service.test.ts"
    ],
    "manualChecks": [
      "Visually inspect button placement on mobile."
    ]
  }
}

Why it matters: This enables autonomous agents to self-verify before asking for human review. Don't just let the agent say "done" — force it to prove success code-first.

Putting It Together

A complete Agent-Ready Spec:

{
  "title": "Header Sign-In Flow",
  "objective": "Users can't find where to log in — 23% of new visitors bounce without attempting sign-in.",
  "problemSeverity": "high",
  "outcomes": [
    "A 'Sign In' button is visible in the header on all pages.",
    "Clicking the button opens a modal with email/password fields.",
    "Successful login redirects the user to /dashboard.",
    "Invalid credentials display an inline error."
  ],
  "evidenceIds": ["evd-1023", "evd-1024"],
  "constraints": [
    "Must not break existing navigation links.",
    "Must use existing AuthContext for state management.",
    "Passwords must never be logged."
  ],
  "edgeCases": [
    {
      "scenario": "User submits with an unverified email",
      "expectedBehavior": "Show 'Email not verified' error with resend link"
    },
    {
      "scenario": "Auth provider is down",
      "expectedBehavior": "Show generic error, do not expose provider details"
    }
  ],
  "verification": {
    "e2eTests": ["login-flow.spec.ts"],
    "unitTests": ["auth-service.test.ts"],
    "manualChecks": ["Visually inspect button placement on mobile."]
  }
}

This is not a document. This is an API payload. It matches the IntentSpec schema that Pathmode uses, and it can be exported directly to Claude Code or Cursor via MCP.

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.

Get Started with Pathmode →