Skip to content
bbakPublic

About

Spec-Driven-Development Tooling, based on Guarded Gherkin and two Agents that never meet each other. Built using itself.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Repository files navigation

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. 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.

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

Install

Download the archive for your platform from the releases, unpack it, and put proviso in a folder on your path.

Set up a repository

The first spec tree is the first amendment, so start on a branch, in the repository's root:

git switch -c first-spec
proviso init

init 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.

Use it

  1. 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 lint checks the notation, proviso diff shows what changed, and proviso impact what it may affect; what the amendment deliberately leaves out goes into proviso/.amendment.md.
  2. 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.
  3. Check: ask it to check the amendment. An independent agent judges whether the tree still holds together; you resolve or dismiss each finding.
  4. 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.

For business requesters

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.

Status

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.

Documentation

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

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.

License

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.

About

Spec-Driven-Development Tooling, based on Guarded Gherkin and two Agents that never meet each other. Built using itself.

Topics

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages