The Veri workflow
Veri is a method carried by five kinds of document. This page teaches the method; the reference covers the file formats behind it.
The core idea: everything an agent needs to do a task well should exist as a document before the task starts — and everything the agent produces should land back in documents you can review. Prompts are ephemeral; files accumulate.
The five document types
| Type | Id | Answers |
|---|---|---|
| Source | SRC-… | "What do we know?" Evidence brought in from outside: interview notes, specs, transcripts, design handoffs. Sources are imported, never authored from nothing — they're the raw material everything else cites. |
| Requirement | REQ-… | "What must be true?" A statement of what the system has to do, with acceptance criteria. Requirements justify work orders — a work order that implements no requirement is flagged. |
| Decision | DEC-… | "What was chosen, and why?" A choice, the alternatives it rejected, and the rationale. Decisions constrain future work: they ride into every context package for tasks they touch, so settled questions stay settled. |
| Work order | WO-… | "What should be done next?" A scoped unit of work an agent can pick up: summary, in scope, out of scope, linked requirements, acceptance tests — and, once work happens, receipts. |
| Workflow | WF-… | "How does work move here?" One per project. It states the path of work and the rules for implementers, and it's the first thing in every context package — so every agent session starts with your project's rules. |
The path of work
Documents aren't filed at random; they flow:
- Evidence enters as sources. A customer call, a planning session, a spec someone sent you — paste it in as a source. It's now citable.
- Sources become requirements and decisions. Reading the evidence, you (or an agent, as drafts) distill what must be true — requirements — and settle the contested choices — decisions, each with its rejected alternatives on the record.
- Requirements become work orders. A work order packages a deliverable slice: which requirements it implements, which decisions constrain it, what's explicitly out of scope.
- Work orders become implementation, with receipts. An agent pulls the work order's context package, does the work, and appends a receipt — date, commit, files touched, summary — to the work order file. Done means: all acceptance boxes checked, at least one receipt.
Each step is a link (implements, constrained-by, informed-by…), and the links are what make context packages possible: given a work order, Veri walks the graph and assembles exactly the documents that bear on it.
The approval gate
Agents write drafts; only you promote them. A requirement an agent files arrives as draft, a decision as proposed — visibly non-binding, queued on your home view under NEEDS REVIEW. Approving (in the app, or veri approve REQ-007) stamps the document with an approval date, and only then does it bind future work.
This is the deal that makes agent authorship safe: agents can capture anything, and nothing they capture becomes canon behind your back. A context package always tells the agent which documents are ratified and which are pending.
Why the loop compounds
- Session two is cheaper than session one. Every decision recorded is a discussion the next agent session doesn't need to have. The knowledge base grows precisely where your project needed explaining.
- Scope rides with the task. "Out of scope" lines in a work order aren't a hope — they're in the package, and the workflow document instructs agents to treat them as forbidden.
- The trail is inspectable. Receipts, decisions, status changes — all file edits, all in git. Reviewing an agent's week is reading a diff.
veri checkkeeps the graph honest. Broken links, work orders with no requirement, done work with no receipt, unapproved promotions — surfaced in the app and failable in CI. Zero issues is the bar.
A worked example
The bundled sample project shows the whole loop in miniature: an invoicing app where a client interview (SRC-001) grounds four requirements, decisions record the stack choices with their rejected alternatives (one superseded, with its successor named), and work orders carry receipts from past agent sessions. Two health issues are left in deliberately so you can see veri check earn its keep. The quickstart walks it end to end.