Taproot 1.0: When the Spec Is No Longer Optional

“A good spec is the highest-leverage input you can give an AI.” I wrote that in my post on Spec-Driven Development. It’s still true. But it has a gap: a spec that isn’t enforced is a spec that erodes.

In the same post I mentioned Taproot as one of five frameworks — my own project, built precisely from that gap. Version 1.0 is out. Time to describe what it does differently.

The problem behind the problem

Almost all established approaches to Spec-Driven Development — PRDs, CLAUDE.md, user stories in a wiki — share one weakness: they are suggestions. The spec sits in the project, the developer is supposed to consult it, the AI agent is supposed to consider it, the reviewer is supposed to check it. Everyone should. Nobody has to.

This works while the team is disciplined and the codebase stays small. In real projects the system drifts: specs go stale, code gets written without a spec, a feature contradicts an architecture decision nobody reads any more. The AI agent applies security rules sporadically — CSRF protection is present in four of five forms, missing in the fifth. This isn’t a problem with the method. It’s a problem with enforcement.

From recommendation to rule

Taproot is built on a single decision: the spec is not a document alongside the code. It is a commit condition.

At every git commit, a pre-commit hook checks three things depending on what is being committed:

• New implementation: The associated behaviour spec must be complete (Definition of Ready) — actors named, acceptance criteria defined, edge cases addressed.
• Source code: Tests must pass, all configured conditions satisfied (Definition of Done).
• Specs: They are checked against the project-wide truths in taproot/global-truths/. A spec that implicitly says “prices are shown including VAT” is rejected if the global truth states “prices are always exclusive of VAT.” The contradiction is caught the day it arises.

The difference from “the spec should be consistent” is not one of degree but of kind. Discipline becomes mechanics.

Requirements as first-class files

Specs live as Markdown files in the repository, in a three-level hierarchy:

taproot/
├── password-reset/        ← Intent: why does this exist?
│   ├── intent.md
│   └── request-reset/     ← Behaviour: what does the system do?
│       ├── usecase.md
│       └── email-trigger/ ← Implementation: how is it built?
│           └── impl.md

Every source file is traceable through this hierarchy to an intent. Conversely, every requirement without code is visible, and every code without a requirement too. Traceability is not a feature that needs separate maintenance — it emerges from the structure.

The work loop comes down to two commands: /tr-ineed user authentication describes a requirement, the agent writes the spec. /tr-implement taproot/auth/ builds code, tests, and traceability. Spec first, code after, the hook verifies both.

New in 1.0: planning across multiple requirements

Most agentic workflows are designed for one requirement at a time. That doesn’t scale when you want to hand an agent ten items before a meeting.

/tr-plan builds a prioritised plan from the backlog and unimplemented specs. /tr-plan-execute works through it — autonomously executable items run through, items requiring human decisions pause. When you come back from coffee, the autonomous parts are done and the open questions are clearly formulated.

What Taproot is not

Taproot writes intents, use cases and implementation specs, manages a backlog and plans execution — functions previously covered by a ticket system and a business analyst. For many projects that’s sufficient. For larger organisations with their own stakeholder processes, Taproot complements the existing ticket system rather than replacing it: the ticket carries the business decision, the Taproot spec carries the technical truth, and both reference each other.

Taproot is not a new agent. It works with Claude Code, Cursor, or Gemini. The logic lives in the files and the Git hook, not in a proprietary runtime — switching agents affects the adapter configuration, not the specs.

And it is not waterfall. Specs evolve; the difference is only that changes are tracked structurally rather than trusting good intentions.

Getting started

npx @imix/taproot init

This installs the adapter and the pre-commit hook. For existing codebases there is /tr-discover, which extracts an initial hierarchy — a workable starting point for brownfield situations you’d otherwise never tackle.

The repository: github.com/imix/taproot. MIT licence. Feedback and issues welcome.

The position

The previous post ended with the thesis that the best AI engineers of 2026 will be those who understood that a good spec is the highest-leverage input you can give. Taproot goes a step further: a good spec is necessary but not sufficient. What’s also needed is a mechanism that guarantees it actually has effect — even when the team is tired, the deadline is pressing, and the reviewer is overloaded.

Whether it succeeds is decided in practice. That’s why 1.0 is a beginning, not a conclusion.

Taproot is developed at Perito IT in Bern. Hands-on workshops on Spec-Driven Development available on request at perito.ch.