Documents

Read in this order

Veldo Development Method

The methodology itself - what Veldo is and why it works.

Audience: Everyone adopting or working under Veldo. Read this first.
Covers: Core model; foundational principles; the change lifecycle from intent to close; risk classification and the emergency lane; repository structure and the index; agent roles and human review lanes; agent operating instructions; definitions of proven and done; what Veldo eliminates and keeps; metrics; failure modes; adoption rules; the manifesto.
Version: 2.2, 2026-08-03

Setting Up and Running Veldo

The operational companion - how to stand Veldo up and run it, from one person to an organization of thousands.

Audience: Whoever sets up or operates Veldo tooling, process, and platform.
Covers: The invariant architecture and the seven contracts with schemas; Claude Code setup; the scaling stages; the control plane and its build order; governance, safety, and economics; the edges (design, intake, documentation); anti-patterns; the two-week pilot and wave rollout.
Version: 2.13, 2026-08-03

Veldo Plugin Guide

Install Veldo into any repository in minutes - the plugin, the init command, and the first change.

Audience: Whoever installs Veldo into a repository or wants the component reference.
Covers: What the plugin carries (agents, skills, guard hook) versus what init lays down (the repository substrate); install commands; the first change end to end; what the guard enforces; the manual no-plugin path; upgrade rules; contents reference.
Version: 2.7, 2026-07-22

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

Audience: Everyone operating under Veldo, daily reference.
Covers: Four full runbooks (backend feature, UI through the design lane, bug from a ticket, protected-path change with commit-bound approval); every change type with infrastructure as code first-class; every situation from a red gate to an emergency; every role's moments in the loop; administration (next repo, policy, standing specs, the weekly pass, upgrades, metrics); the cheat sheet.
Version: 1.7, 2026-07-22

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.

Audience: The founder and anyone leading the transition. Read before announcing anything.
Covers: The truth first (occupational redesign, the three-condition economic fact); the resistance map with counter-moves per role; the research base applied (established frameworks plus the 2024-2026 evidence and the 2026 additions); the program (the public commitment with exact words, the conversion cell, phases 0-4 with exit conditions, the sandbox for safe incompetence, the judgment ladder, pairing redesign, incentives and status protection, measurement without surveillance, the path for those who cannot or will not convert); five hard cases with founder scripts; thirteen program failure modes with tripwires; what never to do.
Version: 1.0, 2026-07-16

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.

Audience: Anyone who files work from a tracker (Jira ticket or Confluence requirements page) and watches its status, working with Veldo.
Covers: Flagging a ticket or requirements page with a routing signal; running intake and what it drafts (a bug's reproduction as AC1, a page's acceptance criteria); the fail-closed refusal on a missing, unknown, or ambiguous signal; the one-way status mirror through the per-org status_map; epic and child structure for a plan; the one-way, repository-wins, never-poll rules; a full round-trip walked through once. Companion to Plugin Guide section 12.
Version: 1.4, 2026-08-10

The role training series

The Veldo Training Guide

The map of the series - who transforms, who dissolves, the shared core, the apprenticeship path, the minimum viable team.

Audience: Everyone; leadership first.
Version: 1.2, 2026-07-16

The Product Manager in Veldo

The most leveraged human role - intent and acceptance criteria as the product craft.

Audience: Product managers and product intent owners.
Version: 1.1, 2026-07-16

The Planning Layer in Veldo

The product manager's other half - driving a whole iteration through Product Plans, the DAG, and the frontier.

Audience: Product managers and product intent owners; anyone stewarding an iteration.
Version: 1.0, 2026-07-16

The Architect in Veldo

The gate is the architecture - policy, protected paths, decomposition, contracts.

Audience: Architects and senior technical leaders.
Version: 1.0, 2026-07-16

The Backend Developer in Veldo

From typing to judgment - specs, proof literacy, gate engineering, the escalation seat.

Audience: Backend engineers.
Version: 1.0, 2026-07-16

The Web Developer in Veldo

The browser domain - the design contract, interaction evidence, baseline judgment.

Audience: Web engineers.
Version: 1.0, 2026-07-16

The Mobile Developer in Veldo

The runtime you cannot roll back - lifecycle evidence, containment, the upgrade matrix.

Audience: Mobile engineers.
Version: 1.0, 2026-07-16

The Infrastructure Engineer in Veldo

The 0-to-100 lever - everything into the repo, plan judgment, recovery as evidence.

Audience: Infrastructure and platform engineers.
Version: 1.0, 2026-07-16

QA in Veldo - the Verification Engineer

The most transformed role - criteria quality, the gate as a product, the exploratory lane.

Audience: QA engineers and SDETs.
Version: 1.0, 2026-07-16

The Project Manager and Veldo

The candid document - the role dissolves; the person has three real destinations.

Audience: Project managers and delivery leads.
Version: 1.1, 2026-07-16

The Designer in Veldo

The mock as a contract, the verdict as a file - design judgment with teeth.

Audience: Designers and design leads.
Version: 1.0, 2026-07-16