Proviso

Proviso keeps one specification of a system true across many changes. The specification is a spec tree: Markdown files beside the system’s code, written in the Proviso Model. Every change to the system starts as an amendment, an edit of that tree on a branch. Proviso checks the tree, works out what the amendment changed and what it may affect, and hands the agents that build and check it exactly what they need.

Proviso serves systems in any language. It reads the spec tree, never the system’s code.

Why

Agents write code faster than anyone can review it. The work that remains sits at the two ends: saying what should be built, and checking that it was. At that volume, checking has to be automated as well: tests written by an agent, independent of the agent that writes the code. Such tests check something only if the specification tells the testing agent enough about the system’s behaviour: what happens when a condition does not hold, where its boundaries lie, what each term means. Where it does not, the agent guesses, and its tests confirm the code instead of checking it. The Proviso Model is written for that reader: rules in Guarded Gherkin, with examples on both sides of every condition, and a glossary that defines their terms. The essay Provided, Otherwise sets out this argument and the format.

A format alone is not enough, though. Every specification leaves something unsaid, and a running system does something in every case anyway. Where the specification is silent, something else decides, often a tool’s default that nobody chose. And where someone did decide, the decision often never reaches the specification: it stays with the change that made it, where the next reader does not look. Over many changes, specification and system drift apart.

A format can make someone decide. It cannot make the decision arrive. Making it arrive takes mechanics nobody performs reliably by hand: finding every rule a change may affect, resolving terms, telling a changed meaning from a reflowed line. Proviso is those mechanics.

The essay Decided Elsewhere sets out the findings behind this.

Design goal

Many spec-driven tools treat a specification as the input to one change: write it, build from it, move on, and let the next change bring the next one. Proviso is designed around a different goal: one specification that stays the system’s lasting statement of what it does. Every amendment is folded into it, with the aim that one tree states the system as it stands, free of gaps and contradictions, so that tests derived from it fail when the code is wrong.

Proviso deliberately trades development speed for that goal. Each change costs more than a prompt or a one-off spec: questions to answer, a check to pass, findings to decide. The trade is meant for systems where a wrong or undecided rule costs more than the time it takes to decide it:

  • Systems that live long and change often, where the people, and the agents, who made last year’s decisions are no longer around to ask.
  • Business rules that are expensive to get wrong, such as pricing, eligibility, limits or compliance, where “the code does something” is not the same as “someone decided it”.
  • Teams that let agents implement at volume, and need tests that check the code instead of confirming it.

What Proviso is built to give in return:

  • Tests with teeth: written by a testing agent that never sees the code, from rules with examples on both sides of every condition, and measured with mutants written by an agent that never sees the tests. Tests with teeth reports that measurement on Proviso itself.
  • No silent defaults: every gap is meant to end either decided by someone or marked as an open question, never filled in by a tool.
  • One current truth: new engineers and fresh agents read one tree, not a pile of change specs to piece together.
  • Impact before build: each amendment lists what it may affect before any code is written.
  • The business reads what it approves, in its own words, through a business view derived from the tree.
  • A gate in CI: no change reaches the main branch without its check.

For behaviour still being discovered by trying, such as prototypes, spikes or throwaway code, this is overhead by design. Explore without Proviso. Once the system is meant to last, proviso-recover writes the spec tree of what it does, and amendments take over from there.

How far Proviso reaches this goal is still being found out; see Limits.

How it works

The path of an amendment: request, specification, build, check, accept

  1. Request. A business requester says what should change, best with the skill proviso-request, which guides them to a checkable request in their own AI assistant.
  2. Specification. An engineer brings the request into the spec tree with the Integrator, a skill that asks the tough questions, on the amendment’s own branch: rules in Guarded Gherkin, a glossary, contracts, invariants, constraints and parameters. Proviso lints the tree and lists what the amendment changed and what it may affect. What only the business can answer goes back to it, with a business view of what was integrated.
  3. Build. A testing agent and a coding agent build from the same context pack, each in its own worktree, without seeing each other’s work. Whatever the tree does not decide comes back to the engineer and is decided in the tree.
  4. Check. An independent checking agent, which sees no code, tests or reports, judges whether the tree still holds together with the amendment. Each finding is resolved by an edit, or dismissed with a reason.
  5. Accept. Once the check covers the amendment, it is merged, and the tree becomes the new baseline. CI tells whether the tree on a branch is either the recorded baseline or an amendment its check covers.

The agents call Proviso; Proviso never drives them. Four skills, installed into the repository, take an amendment through steps 2 to 5; others recover the spec tree of a system that exists already, rehome elements that moved or whose identifiers name no place, and measure the tests with mutants. Claude Code is the first agent host they run on.

Limits

Proviso has been validated only on command-line applications and an MCP server, all written in Go. How it works for systems in other languages, or for systems heavy in user interface or business logic, is untested so far.

The skills and agent definitions were developed with Claude and used only in Claude Code, primarily with Claude Opus 5.5 as the model. How they work with other agent hosts or models is untested as well.

Where to go next

  • Getting started: install Proviso, set up a repository and take a first amendment through.
  • Concepts: the terms the other pages use.
  • Workflow: an amendment from request to acceptance, and what the engineer decides on the way.
  • Writing specs: the spec tree and its notation.
  • Repository setup: CI, the engineers’ notes and what to commit.
  • Commands: every command, its exit statuses and output.
  • Tests with teeth: how many slips Proviso’s own tests catch, measured with mutants.

Proviso specifies itself: its own spec tree is proviso/ in its repository, and it is the exact statement of what every command does.


This site uses Just the Docs, a documentation theme for Jekyll.