Your first verification
In this tutorial, you'll ship a small change end to end through Verify: implement it with your agent, submit the intent through the Aviator MCP, watch verification run, and read the review document.
By the end, you'll have a working loop and a sense of where each piece fits.
Time: ~15 minutes
Prerequisites:
An Aviator org with a connected GitHub repo — see Connect a repository
A coding agent that supports MCP — Claude Code, Cursor, or another MCP-compatible client
Write access to the repo
You don't need a preview to do this tutorial. Without one, Verify runs code-scan only — every criterion is checked against the diff. You'll see a fully working loop end to end. Add a preview later when you want behavioral (runtime) verdicts; see Creating a preview.
Step 1: Install the Aviator MCP in your agent
The MCP is how the agent talks to Aviator. Install it once per agent.
In the Aviator UI, go to Settings → Integrations → MCP and copy your install snippet (it includes a scoped token).
Add the snippet to your agent's MCP server configuration. See your client's MCP documentation for where this lives.
Restart the agent. You should see the Aviator tools listed in the agent's available tools.
A successful install gives your agent access to three Aviator tools: specSubmit, getRunbook, and editRunbook. You only need specSubmit for this tutorial. See MCP tools for the full surface.
Step 2: Pick a small change
For the tutorial, pick something small and concrete. Examples that work well for a first run:
Add a
GET /healthendpoint that returns{"status": "ok"}with a 200.Add a
/versionendpoint that returns the current commit SHA.Add a feature flag check to an existing endpoint.
Keep the scope to one or two files. You're learning the loop, not stress-testing the verifier.
Step 3: Implement the change
Open your agent in the repo. Describe the change normally:
Add a
GET /healthendpoint to the API. It should return{"status": "ok"}with a 200 response and not require authentication.
Let the agent implement it. Iterate until you're aligned on the details — same flow you use today. Don't worry about Verify yet.
When you're happy with the change, tell the agent it's ready.
Step 4: Submit the intent
Tell the agent to submit the intent:
Submit this to Aviator Verify.
The agent calls specSubmit through the MCP. The tool creates a runbook carrying:
Intent — what the change is for, captured from your conversation.
Acceptance criteria — the verifiable assertions, generated from what was built.
The MCP returns a runbook URL like https://app.aviator.co/r/218. The agent will print it.
Open the URL in your browser. You'll see the runbook with the generated plan, the acceptance criteria, and (once verification starts) a streaming verdict per criterion.
Step 5: Watch verification run
The runbook page updates as the verification pipeline progresses. The phases:
Runbook generation. Aviator turns the submission into a structured plan + acceptance criteria. Any matching invariants from your account catalog are materialized as additional criteria.
Preview is built and booted (only if you've configured a preview). Your image is loaded, secrets injected, setup script runs.
Criteria run. Each criterion is routed to one of two verifier paths — code-scan (static analysis of the diff) or runtime (executed against the preview). Without a preview, every criterion routes to code-scan.
For a small change, the whole run completes in 30–90 seconds.
Step 6: Read the review document
When the run finishes, each criterion shows:
Verdict —
pass,fail,warn, orerror.Verifier — which path ran it (Code-scan or Runtime).
Evidence — the diff snippet (code-scan) or runtime output (request/response, screenshot, log line) that backs the verdict.
For the health endpoint without a preview, you should see something like:
Endpoint GET /health exists
Code-scan
✓ Pass
Returns 200
Code-scan
✓ Pass
Response body is {"status": "ok"}
Code-scan
✓ Pass
Does not require authentication
Code-scan
✓ Pass
With a preview configured, the behavioral criteria would route to Runtime instead — and you'd see the actual request + response as evidence.
Click any verdict to see the evidence. If something failed, the verdict is annotated with the file and line that caused it. Fix the issue, then start another run from the runbook UI — a plain push doesn't re-run Verify on its own (see When a run is triggered).
Step 7: Approve (or send back)
From the review document you can:
Approve — sign off and continue your normal merge flow.
Waive a failed verdict with a category —
false_positive,doesnt_apply,accepted_risk, orfix_in_followup. Recorded in the audit trail.Edit the acceptance criteria — ask the agent to call
editRunbookwith the corrected criteria, then re-verify.Open the preview — if you have one configured, poke at the running code yourself before approving.
Approve to close the loop. The audit trail now has a complete record: runbook submission, verdicts per criterion with evidence, your decision.
What you just learned
Verify runs after you build, not before. There's no separate "approve the spec first" step.
The MCP is the only handoff between you and Aviator. One tool call carries everything.
Acceptance criteria come from what was built, not what you planned upfront.
The review document is the surface — verdicts and evidence per criterion, not a 500-line diff.
Reviewer decisions, scenario evidence, and verdicts are all recorded as one immutable audit trail per change.
Next steps
Creating a preview — unlock runtime verdicts. This is usually the next step once you have a feel for the loop.
How Verify works — the full picture
Concepts: Invariants — encode team rules so they apply automatically
Writing a SKILL.md — give the scenario runner the context it needs
Fixing verification failures — what to do when a verdict goes red
Last updated
Was this helpful?
