How Veri builds Veri

Veri's repository is self-hosted: every feature is built by executing a Veri work order, by an AI agent working from a context package, gated by human approval, and closed with commit-provenanced receipts. The veri/ directory holds 85 work orders and 77 decisions in the open. This page traces one of them — WO-077, the team-collaboration semantics — end to end. Nothing here is a mock-up: every document and commit is linked, and you can audit the whole run in the git history.

The feature in question: what happens when a veri/ knowledge base has more than one committer — colliding ids, who may approve, how stamps flow through pull requests. A real feature with design questions, code, tests, and docs. Here is how it moved.

1. The work order is filed — backlog, binding on nothing

Work starts as a document, not a chat prompt. An agent session filed WO-077 as a backlog proposal: a summary of the problem, an explicit in-scope and out-of-scope list, and acceptance tests as unchecked boxes.

commit f7464a2 — WO-076/WO-077: file CI-action and team-story
                  work orders as backlog proposals

Out of scope was as deliberate as in scope: no real-time collaboration, no server, no accounts — files and git remain the whole substrate. An agent that later strays outside that list is deviating from a document it was handed, not from a vibe.

2. The requirement is drafted — and a human approves it

A work order needs a reason to exist. The agent drafted REQ-026 — "A knowledge base with more than one committer" — born draft, because nothing an agent files binds on its own. Then the approval gate did its job:

commit bcc16f2 — draft REQ-025 (CI gate) and REQ-026
                  (multi-committer), link as implements
commit 022d4f2 — REQ-025/REQ-026 approved by Daniel; both
                  work orders promoted to in-progress

The approval is a stamped frontmatter edit — status: accepted plus approved: 2026-08-24 — visible in the diff of that commit. This ordering is enforced, not etiquette: a work order that goes in-progress while linking an unapproved requirement is a veri check error, locally and on every pull request.

3. The agent pulls the context package

An implementing agent doesn't spelunk the repo or get a pasted prompt. It asks the MCP server for WO-077's context package, and gets the workflow rules, the work order, every linked requirement and decision, with token costs stated:

# Context package · WO-077 — Team story: multi-committer
  semantics for a shared veri/ directory   (10 docs · ~10.3k tokens)

Workflow  WF-001  Veri project workflow                    ~513
WO-077    Team story: multi-committer semantics            ~1434
REQ-001   Linked markdown document format       accepted   ~253
REQ-008   Document approval workflow            accepted   ~702
REQ-012   Website and user documentation        accepted   ~581
REQ-026   A knowledge base with >1 committer    accepted   ~805
DEC-002   Markdown files are the source of truth  active   ~286
DEC-070   Ids stay sequential; atomic renumber     active   ~951
DEC-071   Maintainers ride workflow frontmatter    active   ~870
DEC-072   The approval stamp rides the PR          active   ~743

(That's the package as served today — the three DEC-07x rows joined it during this very work order; step 4 is where they came from.) Ten documents, ~10k tokens — the project's constitution for this one task, instead of the whole repo or none of it. REQ-008 rides along so the agent knows the approval rules it must respect; DEC-002 rides along so it knows a server-based design was rejected long ago.

4. Design questions become proposed decisions — and work stops

The task had three genuinely open questions: how id collisions resolve, who may stamp approvals, and where the approval act lives in a PR workflow. The agent didn't just pick answers and code them in. It filed three decisions — born proposed, each with the alternatives it rejected and why — appended a receipt for the session, and stopped:

commit 51840df — design pass — DEC-070/071/072 proposed
                  (id renumber, maintainer stamps, PR approval baseline)
commit 880feaa — receipt — design pass filed as
                  DEC-070/071/072, proposed

The receipt on that first session ends: "No code yet — implementation awaits DEC approval." The three documents are live: DEC-070 (sequential ids, one atomic veri renumber), DEC-071 (a maintainers list in the workflow frontmatter, stamps gain approved_by), DEC-072 (the stamp commit rides the PR; merge never approves). Each records what lost — branch-aware id reservation, UUIDs, bot-written stamps — so no future session relitigates them.

5. A human approves the design

commit 38639a6 — DEC-070/071/072 approved by Daniel

One commit, three frontmatter stamps. This is the whole approval gate: authorship is cheap and agent-friendly; authority requires a human act, recorded in the files where the next context package will serve it.

6. Implementation — and a receipt with a commit to check

With the decisions active, the next session implemented against them: an atomic renumberDocument in core, duplicate-id errors with a guided fix, approved_by validation, veri approve --as, the scaffolded workflow's team rules, and the team docs page. Then it appended a second receipt to WO-077 naming the commit, the files, and what was verified:

commit 10fb4d8 — team semantics — veri renumber, maintainer
                  stamps, team docs

receipt: "…552 tests green; both collision resolution and the
PR-approval walk verified live in a scratch two-branch git repo."

Receipts aren't self-reported theater: veri check verifies them against git — a receipt citing a commit that doesn't exist, or doesn't reference its work order, surfaces as an advisory.

7. Done means checked boxes, receipts, and a green gate

commit d7fe6a3 — WO-077: done — team semantics shipped,
                  all acceptance boxes verified

Every acceptance box in the work order is checked with its evidence inline — which test file, which live verification, which DEC. A work order is done only when all boxes are checked and a receipt exists; veri check holds that line at zero issues, and the same check gates this repo's pull requests.

Why this is the proof

Eight commits, one afternoon, four documents created and two promoted — and the same loop has run 85 times in this repository: the desktop app, the CLI, the MCP server, the Tauri migration, the CI action, and this website were all built this way. If you want to know whether the method survives contact with real software, the evidence isn't this page — it's the corpus itself, where every decision has its rejected alternatives and every "done" has a commit you can check out.