Should we stop writing ADRs if we use Lockstep?

Not necessarily. ADRs remain a good long-form record of why a hard architectural call was made. Lockstep captures the decision itself, keeps it enforced, and links back to the ADR as the source; the two compose.

When are plain ADR files the better choice?

For a small team with strong writing discipline, few repos, and no AI agents in the loop, a well-kept ADR log in the repo is free and version-controlled. The approach breaks down when filing discipline fades or agents need the context mid-session.

Why can't an AI agent just read our ADR folder?

It can, if it knows to, if the ADRs are current, and if the relevant one fits in context. In practice ADR logs are incomplete and stale, and nothing checks the agent's output against them. Lockstep ranks binding decisions by the surface being touched and enforces them at the PR.

Is Lockstep free like adr-tools?

The code is. Lockstep is open source (Apache-2.0) and you can self-host it with docker compose up; a hosted version is available for design partners. adr-tools is also free and open source (GPL-3.0).

Do we need adr-tools to use Lockstep?

No. adr-tools is a command-line helper (adr init, adr new) for creating numbered markdown ADRs, and Lockstep doesn't depend on it. Keep using it if your team likes the workflow.

Lockstep vs ADR files

ADRs are the right instinct (write decisions down) with the wrong reader: a markdown file can't brief an AI agent or stop a conflicting merge. Lockstep is the ADR promise made operational: decisions captured automatically, made binding by their owners, delivered to every engineer and agent, and enforced at the PR.

What ADR files is good at

ADRs in the repo are a great, version-controlled way to record why an architectural choice was made.

Where Lockstep is different

ADRs still rely on someone writing them, and nothing feeds them to an AI agent before it codes. Lockstep captures decisions automatically wherever they happen, gets a one-click confirmation, briefs every agent via MCP, and catches drift before merge.

ADR files vs Lockstep at a glance

	ADR files	Lockstep
Authoring	An engineer writes the ADR by hand, after the fact	Captured automatically from Slack, PRDs, tickets, and PRs
Coverage	Architecture decisions someone bothered to file	Product and engineering decisions across allowlisted sources
Delivery	Sits in the repo; read if someone looks	Briefed to every engineer and agent before they touch the code
Enforcement	None	PR check flags changes that collide with binding decisions
Cost to maintain	Discipline; the log dies when filing stops	No filing; owners confirm with one click
Pricing / hosting	Free; markdown in your repo (adr-tools itself is GPL-3.0)	Open source (Apache-2.0); self-host free, or hosted for design partners
Self-hosting	Inherent: the files live in your own repository	Yes: docker compose up runs Postgres, the API, and the dashboard

ADR files facts checked against: adr-tools on GitHub.

When to use each

They aren't mutually exclusive. Keep ADR files for architecture decision records; add Lockstep as the layer that captures the decisions automatically, makes them binding, briefs engineers and AI coding agents on them, and flags work that conflicts. See the full pipeline.

How ADR files and Lockstep work together

ADRs and Lockstep compose cleanly. The ADR stays the long-form argument for a hard call; Lockstep holds the short, binding rule that falls out of it, plus the many smaller decisions that never earn an ADR because nobody had time to file one.

Keep writing ADRs for the architectural calls that deserve full context, options, and consequences.
During lockstep onboard, select the repo docs Lockstep should read, including your ADR folder.
Lockstep also drafts decisions made in Slack, PRDs, tickets, and PR threads; each owner confirms in one click.
Agents are briefed via get_product_context with the binding decisions for the surface they're touching, and the PR check flags conflicts, linking back to the ADR as the source.

One decision, both ways

Illustrative example: Services never read another service's database directly.

In ADR files

ADR-0012, 'Use the event bus for cross-service data', with context, options considered, and consequences. Read by whoever finds it in the ADR folder.

In Lockstep

A binding decision linked to ADR-0012, briefed to an agent before it adds a query in the orders service, and flagged at the PR if a direct cross-service read appears.

Moving from an ADR log

You don't have to move anything. Leave the ADR folder where it is; Lockstep links decisions back to it. What changes is the filing burden: decisions that would have needed someone to open a new ADR get drafted from where they were made, and the owner only confirms. Install with npm install -g lockstep-cli and run lockstep onboard in the repo.

Frequently asked questions

Should we stop writing ADRs if we use Lockstep?: Not necessarily. ADRs remain a good long-form record of why a hard architectural call was made. Lockstep captures the decision itself, keeps it enforced, and links back to the ADR as the source; the two compose.
When are plain ADR files the better choice?: For a small team with strong writing discipline, few repos, and no AI agents in the loop, a well-kept ADR log in the repo is free and version-controlled. The approach breaks down when filing discipline fades or agents need the context mid-session.
Why can't an AI agent just read our ADR folder?: It can, if it knows to, if the ADRs are current, and if the relevant one fits in context. In practice ADR logs are incomplete and stale, and nothing checks the agent's output against them. Lockstep ranks binding decisions by the surface being touched and enforces them at the PR.
Is Lockstep free like adr-tools?: The code is. Lockstep is open source (Apache-2.0) and you can self-host it with docker compose up; a hosted version is available for design partners. adr-tools is also free and open source (GPL-3.0).
Do we need adr-tools to use Lockstep?: No. adr-tools is a command-line helper (adr init, adr new) for creating numbered markdown ADRs, and Lockstep doesn't depend on it. Keep using it if your team likes the workflow.