How do I let my coding agent check a story is ready before it builds?

Give the agent the Vindex MCP server and one rule: score the story before writing code, and only proceed when the result is Healthy. The agent reads the story from your tracker or from your prompt, calls score_story with the tracker key as the story id, and gets back a band, a finding, and the reasons. What it does with a low band is whatever your rule says.

This works in Claude Code, Codex, Cursor, and GitHub Copilot the same way, because all four can call MCP tools. The rule can be typed into each request while you try it, then moved into the agent’s standing instructions so it runs without being asked; that step is its own guide, putting a Vindex ready check into your agent’s standing instructions.

Why does an agent need a ready check?

Because an agent does not stop at a vague story. A person reading “make scanning faster and better” asks what faster means. An agent picks a number, implements it, writes tests that pass against its own guess, and opens a pull request that looks finished. The review sees working code. The defect is that the code does the wrong thing, and nobody finds that out until the warehouse does.

If your tracker has the Vindex plugin, the story already has a score in Jira or Azure DevOps. The agent cannot read it: the Issue Panel is a human surface, and the plugin’s data is not exposed to tools. The MCP server is how the agent gets the same judgment, in the same call it is already making to fetch the story.

What does the agent send, and what comes back?

The agent passes three fields and an id: the story title, the description as written, the acceptance criteria if there are any, and the tracker key as story_id. It does not summarize or tidy the story first; Vindex judges what the team actually wrote.

The result is structured, which is what makes it usable by an agent rather than only readable by a person:

• health: one of healthy, needs_review, or at_risk. This is the field the rule keys on.
• overall_percent: the score as a whole percentage.
• recommendations: ordered, highest impact first. The first one is the finding the agent reports.
• dimensions: six entries, each with a percentage, reasoning, and suggestions. Testable and Small are the two an agent should read before it plans work.

What should “ready” mean for the agent?

The band is Vindex’s suggestion. The rule is the team’s. A sensible default that most teams start from:

• Healthy (80 to 100): proceed. Use the Testable reasoning to write the acceptance checks before the code.
• Needs review (60 to 79): do not start. Report the finding and the top recommendations, and ask the product owner the open questions. Wait for an answer or an edit.
• At risk (0 to 59): stop. Hand the finding and the recommendations back. There is nothing safe to build yet.

Teams tighten this as they learn what their agents get wrong. A common second version requires Testable at 80 or better on its own, because an agent that cannot verify its work will declare it done anyway. Another requires a real tracker key, so that nothing gets built from a story that only exists in a chat. None of this is enforced by Vindex; it is text in the agent’s instructions, and the team can change it in a minute.

What does it look like on a real story?

Story NW-105 from the Northwind sample backlog reads: “As a customer I want an ETA email when my delivery is delayed,” with a short description and three acceptance criteria (the customer gets an email with the new ETA; it includes the order number and window; the customer can opt out). It looks ready. Scored through the live server, it came back 62%, Needs review: Valuable 90, Negotiable 70, Independent 60, Testable 60, Estimable 50, Small 40.

Under the default rule the agent does not start. It reports the first recommendation as the finding: define the delay trigger and how the new window is calculated, so the work is estimable and testable. Then it asks the product owner the questions the dimensions raise: what counts as delayed, in minutes; does the email go once or on every change; does opting out apply per order or to all future orders. Those are the exact questions an agent would otherwise answer by guessing.

The product owner answers in the story: a 15-minute threshold, one email per delay event, opt-out for all future orders, and the Small suggestion is taken by splitting the opt-out setting into its own story. The agent scores NW-105 again under the same key. The re-check is free, and if it comes back Healthy the agent proceeds, this time with acceptance checks it can actually run.

Where does the check run?

Wherever the agent runs. In Claude Code and Codex, the check is a tool call in the terminal session; in Cursor it happens in Agent chat before the first edit; in GitHub Copilot it runs in Copilot Chat agent mode or inside the coding agent working an assigned issue. Each has a setup page with the connection steps in that platform’s own terms. While you are trying the rule, say it in the request: “Score this with Vindex first and tell me whether you would start.” Once it works, move it into the standing instructions.

What does Vindex not do here?

It does not rewrite the story, and it does not block anything. Vindex returns the band and the reasons; the agent’s instructions decide whether to proceed, and a person decides what the story should say. If an agent stops on At risk, that is your team’s rule working as written, not Vindex refusing. Keep it that way: the moment the check starts editing stories on its own, the product owner stops reading them.