Lockstep Chain Protocol

Chain-based project tracking for Human+AI collaboration. An MCP server that gives your AI coding assistant persistent memory across sessions — chains link work together, tickets track what needs doing, and handoffs preserve context so nothing gets lost between conversations.

Who is this for?

Anyone using AI coding assistants (Claude, etc.) who's tired of re-explaining context every session. Lockstep is especially useful if you:

• Work on multi-session projects where continuity matters

• Want structured session types (discovery, planning, build, review) without rigid enforcement

• Are neurodivergent and benefit from external scaffolding for executive function

• Want your AI partner to track growth and capacity over time

Related MCP server: Adaptive Reasoning Server

Features

• 37 tools + 5 commands for full project lifecycle management

• Chain-based tracking — sessions link together as a chain of work

• YAML-defined chain types — full-funnel, enhancement, refactor, bug-fix out of the box, or create your own

• Progressive disclosure — early phases show fewer fields to reduce cognitive load; information surfaces as it becomes relevant

• Ticket promotion — standalone tickets can be promoted into chains when they grow; related tickets discovered automatically

• Session types — discovery, research, planning, architecture, build, review

• Structured handoffs — decisions, files changed, open threads, and next-session recommendations transfer between conversations

• Capacity tracking — growth stages (training-wheels → partnership → safety-net) with event logging

• Advisory, not enforcing — the protocol flags and explains, never blocks

• Fully local — all data stored as YAML files on your machine, no network access

• Cross-platform — tested on macOS, Windows 11, and Linux (x64 and ARM)

• Human-readable data — inspect, edit, or version-control your project data directly

Installation

From Anthropic Directory (Claude Desktop)

1. Find "Lockstep Core" in the Anthropic Directory

2. Click Install

3. When prompted, choose a data directory (default: ~/.lockstep/data)

MCPB Bundle (Manual)

1. Download lockstep-core.mcpb from the latest release

2. Open it with Claude Desktop (double-click or drag in)

3. When prompted, choose a data directory (default: ~/.lockstep/data)

Manual Setup

Requires uv and Python 3.11+. Works on macOS, Windows, and Linux.

git clone https://github.com/dandelionrosegroup/lockstep-core.git
cd lockstep-core

Add to your Claude Desktop config:

macOS / Linux:

{
  "mcpServers": {
    "lockstep": {
      "command": "uv",
      "args": ["run", "--python", "3.11", "--with", "mcp>=1.0.0", "--with", "pydantic>=2.0.0", "--with", "PyYAML>=6.0", "src/server.py"],
      "cwd": "/path/to/lockstep-core",
      "env": {
        "LOCKSTEP_DATA_DIR": "/path/to/your/data",
        "PATH": "/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/homebrew/bin:~/.local/bin"
      }
    }
  }
}

Important: Claude Desktop is a GUI app and does not inherit your shell's PATH. The PATH entry above ensures uv (typically installed at ~/.local/bin/uv) is discoverable. If you installed uv via Homebrew, /opt/homebrew/bin covers that path.

Windows:

{
  "mcpServers": {
    "lockstep": {
      "command": "uv",
      "args": ["run", "--python", "3.11", "--with", "mcp>=1.0.0", "--with", "pydantic>=2.0.0", "--with", "PyYAML>=6.0", "src/server.py"],
      "cwd": "C:\\Users\\you\\Projects\\lockstep-core",
      "env": {
        "LOCKSTEP_DATA_DIR": "C:\\Users\\you\\.lockstep\\data"
      }
    }
  }
}

Note: On Windows, use double backslashes (\\) or forward slashes (/) in JSON paths.

Troubleshooting

"uv: command not found" or server fails to start: Claude Desktop doesn't inherit your terminal's PATH. Make sure uv is findable:

• macOS/Linux: Add the PATH env var as shown in the config example above, or use the full path to uv (e.g., "command": "/Users/you/.local/bin/uv")

• Windows: The uv installer usually adds itself to the system PATH. If not, use the full path (e.g., "command": "C:\\Users\\you\\.local\\bin\\uv.exe")

Server starts but immediately disconnects:

• Verify Python 3.11+ is available: uv python list (uv will auto-download if needed thanks to the --python 3.11 flag)

• Check Claude Desktop's MCP logs: ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs\ (Windows)

Configuration

Lockstep needs one setting: a data directory where it stores chains, tickets, and capacity data.

• Default: ~/.lockstep/data

• Custom: Set LOCKSTEP_DATA_DIR environment variable or configure during MCPB install

• Lockstep creates subdirectories automatically (chains/, tickets/, capacity/, declarations/, handoffs/, catches/, archive/)

Usage Examples

Start a new initiative

Create a ticket, chain, and first session in one command.

User prompt:

"Create a new initiative called 'Build user authentication' with the vision 'Users can sign up, log in, and manage their accounts.'"

Tool call: cmd_new_initiative

{
  "title": "Build user authentication",
  "vision": "Users can sign up, log in, and manage their accounts."
}

Response:

{
  "ticket_id": "TICKET-001",
  "chain_id": "build-user-authentication",
  "chain_type": "full-funnel",
  "first_session": "discovery",
  "link_number": 1,
  "message": "Initiative created. Discovery session is active. Record your session declaration."
}

Promote a ticket into a chain

When a standalone ticket grows in scope, promote it to get chain tracking with automatic discovery of related work.

User prompt:

"Promote TICKET-005 into a chain. The completion vision is 'OAuth fully integrated and tested.'"

Tool call: promote_ticket

{
  "ticket_id": "TICKET-005",
  "completion_vision": "OAuth fully integrated and tested"
}

Response:

{
  "promoted": true,
  "ticket_id": "TICKET-005",
  "chain_id": "add-oauth-support",
  "chain_type": "enhancement",
  "first_session": "planning",
  "nesting_candidates": [
    {
      "ticket_id": "TICKET-008",
      "title": "Review Auth Flows",
      "shared_tags": ["auth"]
    }
  ],
  "candidate_message": "Found 1 related ticket(s) that could be nested.",
  "message": "Ticket promoted to chain 'add-oauth-support'. Planning session is active."
}

Record a handoff

Capture session context so the next conversation can pick up seamlessly.

User prompt:

"Record a handoff — we decided on JWT tokens and bcrypt for passwords. Files changed: auth.py (created), models.py (modified). Next session should be Planning."

Tool call: record_handoff

{
  "chain_id": "build-user-authentication",
  "session_type": "discovery",
  "status": "complete",
  "decisions_made": ["JWT tokens for auth", "bcrypt for password hashing"],
  "files_changed": [
    {"path": "auth.py", "action": "created"},
    {"path": "models.py", "action": "modified"}
  ],
  "recommended_next_type": "planning",
  "quick_start": "Define API routes, data models, and auth middleware based on JWT+bcrypt decisions."
}

Tools Reference

Chain Lifecycle (15 tools)

Ticket Lifecycle (7 tools)

Capacity Tracking (5 tools)

Query Tools (6 tools)

Session Support (4 tools)

Commands (5 shortcuts)

Creating Custom Chain Types

Chain types are defined as YAML files in templates/. Drop a new file to create a new chain type — no code changes required.

Template Format

# templates/your-type.yaml
chain_type: your-type
display_name: Your Type
phases: [planning, build, review]
autonomous_eligible: false
required_fields:
  - completion_vision
optional_fields:
  - capacity_role
  - parent_chain
progressive_disclosure:
  planning:
    show: [completion_vision, entity, tags]
    prompt: "What are we building and why?"
  build:
    show: [all]
    prompt: null
  review:
    show: [all]
    prompt: "Does this meet the completion vision?"

Fields

Progressive Disclosure

Each phase can define:

• show: List of chain fields visible during this phase. Use [all] to show everything.

• prompt: Optional guidance text surfaced to the AI partner during this phase.

Available fields for show: completion_vision, entity, tags, capacity_role, parent_chain, child_chains, child_tickets, spawn_reason, expected_sequence, gate_skips, all.

Core structural fields (chain_id, title, status, links, etc.) are always visible regardless of disclosure rules.

Built-in Chain Types

Migrating from v0.1.0

If you have existing v0.1.0 data, run the migration script:

python scripts/migrate_v1_to_v2.py ~/.lockstep/data

This creates a backup, renames template to chain_type, and bumps the schema version. The server also auto-migrates any v1 files it encounters on read, so migration is optional but recommended for clean data.

Design Principles

1. Advisory, not enforcing. The protocol flags and explains — it never blocks. If you want to skip from Discovery straight to Build, it records the skip and moves on.

2. Make the unconscious conscious. Session handoffs, catch events, and capacity tracking illuminate patterns over time without forcing behavior change.

3. Scaffold growth, respect autonomy. Growth stages (training-wheels → partnership → safety-net) make the path of least resistance the productive path, but they're never the only path.

4. Protocol serves partnership. If the structure fights the work, the structure bends.

Data Storage

All data is stored as YAML files in your configured data directory:

~/.lockstep/data/
├── chains/          # CHAIN-[kebab-title].yaml
├── tickets/         # TICKET-[number].yaml
├── capacity/        # [role-name].yaml
├── declarations/    # Session declaration records
├── handoffs/        # Session handoff records
├── catches/         # Catch event records
└── archive/         # Completed chains and tickets
    ├── chains/
    └── tickets/

YAML files are human-readable and version-controllable. No database required.

Privacy Policy

Lockstep is a fully local MCP server. It collects no data, makes no network requests, and includes no telemetry. Your project data stays on your machine.

Full policy: PRIVACY.md

Support

• Issues: github.com/dandelionrosegroup/lockstep-core/issues

• Discussions: github.com/dandelionrosegroup/lockstep-core/discussions

Contributing

Lockstep is GPL v3 licensed. Contributions welcome. Tested on macOS, Windows 11, and Linux.

# Set up development environment
git clone https://github.com/dandelionrosegroup/lockstep-core.git
cd lockstep-core

# Run tests (uv handles dependencies automatically)
uv run --python 3.11 --with mcp --with pydantic --with PyYAML python tests/test_integration.py
uv run --python 3.11 --with mcp --with pydantic --with PyYAML python tests/test_phase2_promotion.py
uv run --python 3.11 --with mcp --with pydantic --with PyYAML python tests/test_phase3_disclosure.py

# Or run all tests with pytest (requires pytest + pytest-asyncio)
uv run --python 3.11 --with mcp --with pydantic --with PyYAML --with pytest --with pytest-asyncio \
  python -m pytest tests/ -v

Check open issues for good places to start.

License

GNU General Public License v3.0 — Copyright (C) 2025-2026 Jack Daniel Williams / Dandelion Rose Group, LLC

Built as part of Dandelion Rose Group's mission to prove that neurodivergent minds are uniquely wired for AI partnership.