Core Concepts
Acceptance criteria
The must/should priority scale, the four verification methods, and the guard logic that blocks marking a story done.
Acceptance criteria are what turn "I think this is done" into something checkable. Each criterion on a story has:
- Text — the plain statement of what must be true.
- A priority:
mustorshould. (This is a separate, narrower scale than a story'smust/should/couldpriority — a criterion without a priority defaults toshould.) - A verification method — how it gets checked.
- A last result — the outcome of the most recent check, who reported it (
agentorhuman), and when.
Verification methods
| Method | What it means |
|---|---|
executable | A literal shell command with an expected result. intent check (and the MCP report_criteria tool) can run it and get a real pass/fail — no judgment call involved. |
agent_self_check | A prompt describing what to verify; an agent evaluates it and self-reports the result. |
visual_render | Requires visually inspecting a rendered UI — an agent with vision, or a human, confirms it. |
founder_confirm | Requires a human (typically the founder) to confirm it directly — not something an agent can close out on its own. |
Only executable criteria are something intent check actually runs; the other three are printed as manual (⬜) and skipped, since there's nothing to execute.
The must-criteria gate
A story can't be marked done while a must criterion's last reported status isn't pass — that includes criteria that are fail, blocked, or have never been reported at all. should criteria (and legacy criteria with no priority set) never block completion.
This gate is enforced in two places that both eventually agree with each other:
- CLI:
intent done <id>lists the blocking criteria and asks "Mark done anyway?" — you can override, which is recorded asforced: true. - MCP: the
mark_done(local server) /complete_story(remote server) tool returns the blocking list instead of completing, unless the caller passesforce: true.
The gate exists so "done" means what it says — an agent (or a human moving fast) can't silently skip past a must requirement without that override being visible in the activity log.
Reporting results
- CLI:
intent check [idPrefix] --reportruns every executable criterion locally and posts the results back, taggedreported_by: human. - MCP: the
report_criteriatool takes{ story_id, results: [{ criterion_id, status, detail, attempt? }] }— this is the feedback channel agents use after implementing and evaluating each criterion themselves, taggedreported_by: agent.
detail matters — it's the evidence for the result, not a formality. "Ran npm test -- auth.spec.ts, 12/12 passed" is a useful detail; "done" is not.
Where executable criteria connect to real test infrastructure
An executable criterion's command is just a shell command — it can be anything, including a call into your test suite. If you're using verification-core to write markdown-native executable specs, an acceptance criterion's command can point straight at running that suite (e.g. vitest run docs/checkout.spec.md), so the acceptance criterion and the actual verified spec stay the same source of truth instead of two things that can silently disagree.