Proviso keeps one specification of a system true across many changes. The specification is a spec tree: Markdown files beside the system's code. Every change 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. It serves systems in any language, and never reads their code.
Agents write code faster than anyone can review it, so checking it has to be automated as well: a testing agent, independent of the coding agent, derives tests from the specification. Those tests check something only if the specification states the system's behaviour precisely: what happens when a condition does not hold, where its boundaries lie, what its terms mean. The spec tree is written for that reader, and Proviso keeps it true as the system changes: a format can make someone decide, but it cannot make the decision arrive.
Proviso's design goal is a specification that stays coherent across many changes, and tests that fail when the code is wrong. It deliberately trades development speed for that: it is meant for long-lived systems with rules that are expensive to get wrong, and is overhead for prototypes and explorations, where a recovered spec tree can follow once the system is meant to last. See the design goal.
Download the archive for your platform from the
releases, unpack it, and put
proviso in a folder on your path.
The first spec tree is the first amendment, so start on a branch, in the repository's root:
git switch -c first-spec
proviso initinit writes the start of the spec tree in proviso/, the skills and
agent definitions for Claude Code in .claude/, and stubs for your
notes in .proviso/. Name your project's build and test commands in
.proviso/build.md, and commit everything.
- Integrate: ask Claude Code to integrate a request, in any form.
The Integrator works it into the tree with you on the amendment's
branch, asks the questions the tree needs answered, sends what only
the business can decide back as questions, and checks the result. Or
edit the tree yourself:
proviso lintchecks the notation,proviso diffshows what changed, andproviso impactwhat it may affect; what the amendment deliberately leaves out goes intoproviso/.amendment.md. - Build: ask Claude Code to build the amendment. A testing agent and a coding agent build from the tree, apart from each other; every decision the tree did not make comes back to you.
- Check: ask it to check the amendment. An independent agent judges whether the tree still holds together; you resolve or dismiss each finding.
- Accept: ask it to accept the amendment. It is merged, and the tree becomes the new baseline.
To see whether the tests have teeth, ask Claude Code to measure them
with mutants: proviso-mutate has an agent that never sees the tests
write one small slip per rule into the code, and reports every slip
the tests let through, as a hole in the tests or in the tree.
For a system that exists already, ask Claude Code to recover its spec
tree: proviso-recover writes what the system does, one capability per
amendment, with the questions that let the business confirm it.
Run proviso verify in CI, so that no amendment reaches the target
branch unchecked.
Requesters never see the spec tree. The skill proviso-request guides
them through a short session with their own AI assistant to one request
file, which the Integrator reads best: what is wanted and why, the rules
with examples, the words that need pinning down, and what is still
open. Each release carries it as proviso-request_<version>.skill.zip,
for any assistant that reads Agent Skills, such as Claude, ChatGPT,
Microsoft Copilot or Gemini. Its check needs Python 3, which those
assistants bring along; without it, the skill checks by reading.
Proviso has been validated only on command-line applications and an MCP server, all written in Go, with Claude Code and primarily Claude Opus 5.5.
The documentation covers
getting started,
concepts, the workflow,
writing specs,
repository setup and the
commands. Proviso specifies itself: its own spec tree
is in proviso/.
Building Proviso needs Go, Task
and Python 3, for the tests of the request
skill's check; task snapshot also needs
GoReleaser. task build builds the binary
into bin/, and task check runs every check before a push.
Copyright 2026 Bruno Baketarić. Licensed under the Apache License, Version 2.0. The binary contains code from other projects under their own licenses; see THIRD_PARTY_NOTICES.md.
Proviso is a personal project, built in my own time. It is not affiliated with, sponsored or endorsed by my employer.
