Veldo

The loop

Every change follows the same fundamental path:

Intent -> Specification -> Implementation -> Proof -> Independent Review -> Merge

A human states what should change and how success will be recognized. An AI coding agent implements the change. Automated checks prove that the implementation meets the specification and does not violate repository constraints. A fresh-context agent independently reviews the specification, implementation, and evidence. The change merges automatically when all required gates pass, except when the change affects an area where an incorrect decision would be difficult or impossible to reverse.

The unit of delivery is therefore not code alone. The unit of delivery is:

Specification + Implementation + Evidence

Code without evidence is incomplete.

That path is the spine of every change. Above it sits one more layer, for product work only. A product increment (several features, many specifications, shared regression) is defined holistically before it is decomposed, so specifications are pulled from a deliberate order rather than arriving as a random stream. A bug or an isolated change skips that layer and enters the path directly. Principle 2.11 states the two lanes; Stage 0 in the lifecycle defines the planning layer and how work flows out of it.

Source: Veldo Development Method, 1. Core Model

What proven means

A change is proven when all of the following are true:

• The specification is clear and versioned.
• Every acceptance criterion has corresponding evidence.
• The implementation is complete.
• Relevant tests pass.
• Repository-wide mandatory gates pass.
• The evidence is reproducible.
• Independent review passes.
• Risks are documented.
• Rollback or recovery is understood.
• Required human approval has been recorded.

"Works on my machine" is not proof. "The agent says it is done" is not proof. "A test passed" is not sufficient when the test does not establish the required behavior.

Proof means that the available evidence justifies shipping the change.

Source: Veldo Development Method, 9. Definition of Proven

The one rule

The methodology can be reduced to one rule:

State the intent, let the machine build, require proof, and merge immediately when green.

That rule should govern every ordinary change.

The repository states what is true. The specification states what should become true. The implementation changes reality. The gate proves the result. The independent reviewer challenges the proof. The trunk records the new truth.

That is Veldo.

Source: Veldo Development Method, 22. The Veldo Rule

Start here

2. Install

From the marketplace hosted in the Veldo repository:

/plugin marketplace add Bcengi/veldo
/plugin install veldo@veldo

The repository's .claude-plugin/marketplace.json is what makes veldo@veldo resolvable: the first veldo names the plugin, the second the marketplace.

Then, once per repository:

/veldo:init

Init copies the templates into the repository without overwriting anything that exists, prepends the Veldo rules to an existing CLAUDE.md rather than replacing it (behind an idempotency marker, so re-running init never duplicates the block), and then configures with you, not for you: the real format, lint, type, test, and build commands go into scripts/verify.sh, and the paths where being wrong is unrecoverable go into .veldo/policy.yaml. It finishes by running the gate once and validating the contracts. Everything lands as uncommitted files: you review and commit the initialization like any other change. In fact, initialization IS the repository's first Veldo change: give it a specification, run the gate, produce proof, exactly as the pilot repository did. The guard's evidence rules (below) are what let that first push carry its own proof.

Source: Veldo Plugin Guide, 2. Install

3. The first change

1. /veldo:spec <what you want> - the spec agent interviews you and drafts the specification; you approve it to ready.
2. /veldo:run VELDO-0007 drives everything that follows: implementation, the gate, the proof manifest, and the fresh-context review (dispatched to the veldo-reviewer subagent), ending with a receipt of what was proven and whether anything awaits a human. The individual steps (/veldo:gate, /veldo:proof, /veldo:review) remain available for inspection and debugging.
3. Merge. The guard blocks mechanically when the gate is not green for HEAD, proof is missing, no passing verdict is bound to the commit, a protected path lacks a live approval, or an emergency debt is open. Branch protection can enforce the same server-side; the plugin does NOT configure it - the repository owner must, before claiming server-side enforcement.

A small change runs end to end in minutes rather than days, and every step after the spec is agent work.

Source: Veldo Plugin Guide, 3. The first change

The documents

1. Veldo Development Method. The methodology itself - what Veldo is and why it works.
2. Setting Up and Running Veldo. The operational companion - how to stand Veldo up and run it, from one person to an organization of thousands.
3. Veldo Plugin Guide. Install Veldo into any repository in minutes - the plugin, the init command, and the first change.
4. The Veldo Runbook. The complete operational manual - every change type, situation, and role, keystroke-exact; the document that takes a team from 0% to 100%.
5. Changing to Veldo - The Human Transition. How to move every person to Veldo without firing anyone - resistance mapped role by role, the funded commitment, the phased program, the hard cases with scripts, and the program's own failure modes.
6. Working with Veldo and Your Tracker. The operator companion to the tracker integration - the human workflow for filing work from Jira or Confluence and the ticket round-trip that follows.

All documents, including the 11 role training documents.

What it values

We value:

• Proven outcomes over completed tasks
• Repository truth over external coordination
• Explicit intent over inferred requirements
• Executable acceptance criteria over subjective completion
• Independent evidence over author confidence
• Small reversible changes over large coordinated releases
• Continuous delivery over artificial iterations
• Automated gates over ritual approval
• Human judgment over human labor
• Verification speed over code-generation volume

The items on the right may still have value, but the items on the left define the system.

Source: Veldo Development Method, 20. Veldo Manifesto