Lockstep README

Lockstep

Keep decisions consistent. Turn product briefs into clear implementation context.

Start with one developer or one product manager. Grow into a shared decision record for your team.

Website · ▶ Try it live · Quick start · For product managers · How it works · Deploy

Yesterday, you and Claude renamed POST /login to POST /session. Today, a fresh session writes a client against the old route. The decision was made; the next session never received it.

Lockstep gives developers and product managers two ways to start independently:

• Developers: keep accepted decisions across Claude Code sessions and check whether changed code may contradict them.
• Product managers: turn a product brief into reviewed requirements, track revisions, and copy a useful implementation brief before a developer joins.
• Teams: share the same ledger, route interface changes to affected services, and retain existing integrations, permissions, and PR enforcement.

For example, accept “exports expire after 24 hours, except internal previews.” A later Claude session receives that decision without another explanation. A PM can trace the requirement to its source, revise it for review, and share its accepted version with a developer.

Start with one real repo or brief. Invite a colleague when there is useful context to share; company-wide onboarding is not required.

npx lockstep-cli onboard

How it compares

How It Works

Start with your own next session:

You accept: “Use POST /session; POST /login is retired.”
    → Lockstep keeps the accepted decision.
    → Your next Claude session receives it before you start coding.
    → An opted-in check can flag changed code that may contradict it.

A decision is a durable rule or architectural choice that shapes future work. A change is a routine event — captured, but only surfaced when it matters. A PM can establish the same continuity by reviewing requirements from a brief before any code is connected.

As teammates join

The same ledger grows into coordination across developers and repos. For example, a route change in one service can reach the developers whose services consume it:

  Dev A's agent                  Lockstep                       Dev B's agent
  ─────────────                  ────────                       ─────────────
  logs a decision  ───────▶  ┌─────────────────┐
  "auth → /session"          │  Decision ledger │
                             │  Usage graph     │  blast radius
  changes a surface ──────▶  │  Impact ranking  │  decides who
  POST /session              │  Inboxes         │  cares & how much
                             └────────┬─────────┘
                                      │  routes to the services that
                                      ▼  consume the changed surface
                              Dev B's next session begins with:
                              ⚠ [impact 3] auth: /login → /session (binding)
                              → B's agent uses /session before writing a line

1. Capture — A coding-agent hook diffs the working tree and publishes changes with a canonical surface ID (http:POST /session, proto:auth.v1.Auth/Login). When an agent makes a real decision, it logs it with propose_decision.
2. Rank — Each decision and change gets an impact score = how many services consume the affected surface (its blast radius). This is what keeps signal high and noise quiet.
3. Route — Changes fan out to exactly the repos that declared a dependency on the changed surface (lockstep.yaml). The agent can also ask consumers("http:GET /orders/:id") — "does anyone use this?" — and get an answer from the graph instead of pinging a human.
4. Replay — On session start, each agent receives a briefing of what changed and what's binding since it was last here, highest blast radius first — so it's aware before it acts.
5. Bind — Cross-cutting decisions (high impact) stay open until an affected team acknowledges them; own-area decisions bind on assertion. A PR-time gate fails any contract change with no binding decision.

Quick Start

Choose your starting point: developer or product manager. Both use the full dashboard and the same project history.

Pilot release status: CLI 0.3.0 is published on npm and listed in the MCP registry, alongside the matching API and dashboard changes in this repository. Hosted rollout and a real authenticated Claude-session verification are still pending, so the hosted links may run an earlier release. Complete those checks before inviting pilot participants.

For developers

Requires Node.js 20+, Claude Code, a GitHub account, and a Git repo with an origin remote.

cd your-project
npx lockstep-cli onboard

1. Preview locally. Inspect candidate documentation and proposed Claude configuration changes before approving setup. Select which documents to upload, or skip import and enter a decision manually.
2. Connect, scan, and review. Sign in with GitHub and connect the intended project. Onboarding runs scan --apply: it writes or merges lockstep.yaml, preserving existing entries, and seeds the graph with detected produced surfaces and matched dependencies. Then review up to five decision proposals. Remaining drafts stay in Review. Imports do not become accepted decisions automatically.
3. Choose hosted checks separately. Automatic code checks have their own remembered opt-in. Declining them leaves decision continuity available.
4. Open Claude Code. Approve the project MCP server when prompted. Onboarding distinguishes configured, connected, decisions ready, and agent verified. Use npx lockstep-cli status to inspect configuration and recorded agent verification. Configuration alone is not activation.
5. Return, share, and invite. Later sessions receive current decisions and relevant updates. Use the dashboard's Preview decision brief → Copy decision brief, or print Markdown with npx lockstep-cli brief. When the scan finds outbound calls with no declared producer and relevant Git history, onboarding also suggests recent contributors to the calling files and prints an invite command.

For example, an unmatched http:POST /billing/charge call in src/checkout.ts can point you to a colleague who recently edited that file. These are leads to ask about the missing dependency, not verified owners; an unmatched call may also target an external service. Confirm the GitHub handle and invite each person you choose:

npx lockstep-cli invite <github-handle>

Suggestions do not send invitations automatically. You can share a useful brief with the colleague first.

npx lockstep-cli onboard --dry-run    # preview without configuring or uploading
npx lockstep-cli check --upload       # explicitly authorize this one working-diff check
npx lockstep-cli check --base main --upload
npx lockstep-cli checks on            # enable automatic hosted checks for this checkout
npx lockstep-cli checks off           # disable them independently of the ledger

For non-interactive runs, authenticate first and use --yes to proceed beyond preview:

npx lockstep-cli onboard --yes --no-docs --disable-checks
npx lockstep-cli onboard --yes --upload-docs --docs CLAUDE.md,docs/adr/auth.md --disable-checks

--yes approves setup; it does not authorize document uploads or enable hosted checks. --no-docs skips documentation import, while --upload-docs explicitly authorizes uploading the selected candidate documents (--docs narrows that selection). Neither skips the repository scan and graph setup. Non-interactive imports remain drafts for dashboard review. Use --enable-checks or --disable-checks to set check consent explicitly; otherwise saved consent is retained.

Checks are advisory and report completed, partial, skipped, or unavailable. Missing providers or applicable rules do not produce a pass. Automatic checks have a six-second API deadline and never block Claude. Raw diff hunks are processed transiently; stored results contain status, decision references, locations, and feedback.

Onboarding respects LOCKSTEP_API_URL and saved API settings; hosted is the default only when neither exists. Generated Claude commands use a version-pinned npm invocation, so a global Lockstep installation is unnecessary. Decision packs stay local and Git-ignored.

For product managers

Start with a brief, without a repo, CLI, or developer. Sign in with GitHub at the dashboard, then:

1. Create a project. Use Start with one product brief on the dashboard home page. New pilot projects enable the product layer; joining an existing project preserves its settings.
2. Paste your brief in Sources. Give it a title and, optionally, a feature reference such as feature:private-exports. Save it and inspect the extracted requirements alongside their source evidence. If extraction is unavailable, open the saved brief and use Select requirements manually to choose exact source passages.
3. Review and ratify. Inspect the source, set its state to active when ready, and edit, reject, or ratify requirements through Review and Decisions. Drafts and questions remain distinct from accepted requirements.
4. Use the implementation brief. Open the source and choose Preview implementation brief, review the Markdown, then Copy implementation brief. It includes accepted requirements, rationale and source references, drafts, unresolved questions, and recorded concerns. You have a useful handoff before anyone installs Lockstep.
5. Revise with history. Edit the saved source when the product brief changes. Previous source versions remain available; changed requirements return to review before the accepted brief is regenerated. Pasted briefs are manually maintained, not synchronized with an external document.
6. Invite a developer when ready. Use Members & Repos to invite their GitHub handle to this exact project. Share the brief and its project/feature connection command. Their Claude sessions can then receive the relevant ratified requirements.

For example, a PM can start with “exports expire after 24 hours; internal previews are exempt; bulk downloads are out of scope.” Review those requirements, leave “Should expiry be configurable?” as an unresolved question, and copy the implementation context before involving engineering.

Once development is connected, use the existing decision, feature, check, and activity views to review recorded context and concerns. Delivered requirements and no recorded concerns do not mean a feature is complete. Useful-concern, false-positive, and intentional-exception feedback does not silently change a decision.

Copying Markdown does not publish it, send a message, or grant access. Dashboard links remain authenticated. A product colleague joining a developer-created project uses the same dashboard and ledger, with no CLI setup.

Join an existing project

After the project owner invites your GitHub handle, sign in again to activate the invitation. Developers connect their repo to the supplied project ID:

npx lockstep-cli onboard --project-id <project-id> --feature feature:private-exports

Omit --feature when no feature is selected. This reuses the project's ledger and history. Each developer installs personal Claude hooks; product colleagues work in the dashboard.

For teams and self-hosting

Existing B2B integrations, roles, review requirements, and GitHub PR checks remain available. The new semantic code checks are advisory; they do not replace the existing contract gate. The individual pilot starts with Claude Code; other adapters are deferred.

Onboarding already runs scan --apply to establish lockstep.yaml and seed the surface graph. When routes or dependencies change, use npx lockstep-cli scan to preview updates and npx lockstep-cli scan --apply to merge and sync them. The standalone command also retries a scan that was incomplete during onboarding. See lockstep.example.yaml. Independent login, init, connect, scan, and pack commands remain available.

git clone https://github.com/lockstep-team-agent/lockstep.git
cd lockstep
cp .env.example .env
docker compose up --build   # Postgres + API (:8080) + dashboard (:3000)

npx lockstep-cli login --api http://localhost:8080

npx lockstep-cli login --api http://localhost:8080 --dev --dev-id 1 --dev-login alice

What flows through Lockstep

Standards & Skills (organizations) — Claude Code pilot

Behind LOCKSTEP_STANDARDS=1 (see DEPLOY.md), an organization can define how agents should work and prove what reached each checkout. This is a Claude Code pilot, not the complete PRD: pausing/resuming a rollout, Codex, enrolling a repo-free PM workspace, readiness checks for a skill's declared tools, owner reassignment and linking supporting decisions in the standard editor, and author-facing conflict flagging are not built yet. The Map graph shows the first page of an expanded domain (the Outline lists everything).

• Standards & Skills — versioned standards (requirements with stable keys and required/recommended levels), skills authored in Lockstep or imported from a public GitHub repo at an exact commit, and checks (PRD sections, PRD rubric, advisory code review). Published versions are immutable; members draft and propose, owners/admins publish.
• Rollouts & Adoption — assign exact versions by project, repository, team or person, path and task type; preview the impact before applying; pilot, expand, roll back, retire or withdraw. Adoption reports coverage, installation, session availability, invocation (reported as unobservable where the agent can't show it) and check outcomes separately.
• In the work — enrolled checkouts (lockstep enroll) receive managed skills in .claude/skills/lockstep-org-*/ (kept out of git, verified by hash, never executed, never overwritten when edited locally). Session briefings list the applicable requirements with exact versions and point to the relevant skills; the copyable project brief carries the same for repo-free PRD work. Exceptions are requested and approved per requirement, bind to the exact published version (a new version needs a new review), and expire on their own.

Agents & integration

The individual pilot supports Claude Code only, with session-start briefings, MCP tools, local decision packs, and optional completion checks. Explicit CLI/MCP operations remain available if hooks are unavailable. No model calls run after every edit.

The ledger remains vendor-neutral and the existing team integrations are retained. Codex and other individual-onboarding adapters are deferred.

CLI Commands

Use npx lockstep-cli <command> without installing a global binary, or lockstep <command> if installed globally.

Project Structure

packages/core/   # Fastify API + PostgreSQL (Drizzle ORM), RLS-isolated, append-only ledger
packages/cli/    # lockstep-cli — onboarding, continuity, advisory checks, MCP server
packages/web/    # Next.js dashboard — briefs, review, decisions, features, team workflows
actions/pr-check # GitHub Action — PR-time reconciliation gate

Learn more

• Deploy · Contributing · Security · Changelog
• Built on row-level-security Postgres, an append-only CAS-versioned decision ledger, and vendor-neutral MCP adapters. Self-host with docker compose or deploy to Railway.

License

Apache 2.0 © 2026 Naman Jain