lockstep

<p align="center"><strong>Lockstep</strong></p>

<h3 align="center">Keep decisions consistent. Turn product briefs into clear implementation context.</h3>

<p align="center">Start with one developer or one product manager. Grow into a shared decision record for your team.</p>

<p align="center">
  <a href="https://github.com/lockstep-team-agent/lockstep/actions/workflows/ci.yml"><img src="https://github.com/lockstep-team-agent/lockstep/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://www.npmjs.com/package/lockstep-cli"><img src="https://img.shields.io/npm/v/lockstep-cli" alt="npm version"></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="Apache 2.0 License"></a>
  <a href="https://glama.ai/mcp/servers/lockstep-team-agent/lockstep"><img src="https://glama.ai/mcp/servers/lockstep-team-agent/lockstep/badges/score.svg" alt="Lockstep MCP server quality and maintenance score on Glama"></a>
  <img src="https://img.shields.io/badge/TypeScript-strict-blue" alt="TypeScript strict">
</p>

<p align="center">
  <a href="https://www.getlockstep.dev"><b>Website</b></a> ·
  <a href="https://lockstep-dashboard.up.railway.app"><b>▶ Try it live</b></a> ·
  <a href="#quick-start"><b>Quick start</b></a> ·
  <a href="#for-product-managers"><b>For product managers</b></a> ·
  <a href="#how-it-works"><b>How it works</b></a> ·
  <a href="./DEPLOY.md"><b>Deploy</b></a>
</p>

---

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.

<p align="center">
  <img src="docs/assets/new-stack.png" alt="The new stack for software development: code stays in GitHub, agents read and write it, and the decision &amp; coordination layer (Lockstep) sits on top." width="860">
</p>

<!--
  Once recorded, the 25s two-developer demo GIF (storyboard in docs/DEMO.md) can become the lead visual,
  moved above the problem statement: <img src="docs/assets/demo.gif" alt="Lockstep in action" width="820">
-->

```bash
npx lockstep-cli onboard
```

### How it compares

|                                                     | Nothing | Slack / docs | CODEOWNERS |         **Lockstep**          |
| --------------------------------------------------- | :-----: | :----------: | :--------: | :---------------------------: |
| Agents learn what other agents decided              |   ❌    |    Manual    |     ❌     |         ✅ Automatic          |
| Decisions ranked by blast radius                    |   ❌    |      ❌      |     ❌     |        ✅ Usage graph         |
| Changes routed to the services that consume them    |   ❌    |      ❌      |     ❌     |      ✅ Dependency graph      |
| "Does anyone use this endpoint?" answered instantly |   ❌    |    Manual    |  Partial   |       ✅ From the graph       |
| Claude Code session continuity                      |    —    |    Manual    |     —      | ✅ Briefings + decision packs |

## How It Works

Start with your own next session:

```text
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](#for-developers) or [product manager](#for-product-managers). Both use the full dashboard and the same project history.

<!-- Release maintenance: after hosted rollout, verify both entry paths and a real authenticated Claude session, then replace this pending note with the verified status. -->

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

```bash
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:

```bash
npx lockstep-cli invite <github-handle>
```

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

```bash
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:

```bash
npx lockstep-cli onboard --yes --n