From e253baf0f21d1f1ea95a36c8b44d6bd0513ba117 Mon Sep 17 00:00:00 2001 From: mmilanez Date: Sun, 31 May 2026 18:27:34 -0400 Subject: [PATCH] docs: README 2.0.2 - consumer-facing documentation overhaul --- CHANGELOG.md | 36 +++++++++++ CONTRIBUTING.md | 4 +- README.md | 161 ++++++++++++++++++++++++++---------------------- 3 files changed, 126 insertions(+), 75 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 41191a1..e129a4f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,42 @@ re-stated here. --- +## [2.0.2] — 2026-05-31 + +Documentation overhaul of the consumer-facing `README.md`. No kernel, schema, +or tooling changes — the framework `PROTOCOL_RULES.md` version stays at `2.0.0`. +This release only restructures and clarifies how the protocol is presented to +new users. + +### Changed + +- `README.md` opening rewritten for non-technical readers. The tagline is now + the plain-language analogy ("a shift-change logbook for your AI coding + assistants"); "The problem" opens with a concrete, relatable scenario instead + of a list of engineering verbs. Vendor/tooling jargon (mem0, LangGraph, the + agent-stack diagram) moved into collapsible `
` blocks labeled "For + developers" so beginners are not blocked while developers still find it. +- `README.md` solution section now describes each state file by everyday use + (handoff = current state, decisions = why, lessons = mistakes not to repeat) + and embeds the folder-layout diagram immediately, so the product is visible + before the install instructions. +- "Checking which version you have" now explains that `PROTOCOL_RULES.md` records + the **kernel** version (a floor, not the release number) — e.g. release + `2.0.1` ships kernel `2.0.0`. The installed release is the top entry of + `CHANGELOG.md`. (Partial pre-work for the documentation acceptance criterion + of #6; the verification tooling remains scoped to v2.1.0.) + +### Fixed + +- Removed an orphaned "Option 2" heading left over after the duplicate + `git clone` block was merged into Quick start (now "Alternative"). +- "Read the operational manual" link now points to `.agents/CORE_RULES.md` + (how agents use the protocol) instead of `.agents/modules/README.md` (a + narrower module index). +- Collapsed the pre-`v1.8.0` version history into a `
` block rather + than moving it out, preserving the `CHANGELOG.md → README.md#version-history` + back-reference. + ## [2.0.1] — 2026-04-23 Bugfix patch from the first external consumer migration. No kernel diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 88c4eae..6ec8ba2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,8 +82,8 @@ If your contribution touches the `.agents/` directory: - **`PROTOCOL_RULES.md`** — do not modify directly. Propose changes via an issue first. - **`PROJECT_RULES.md`** — bump version (`X.Y`) on structural changes. -- **`handoff.md`** — follows an immutable schema. Do not add new fields. -- **`decisions.json`** — append-only. Never edit past entries. +- **`handoff.md`** — located in `local///handoff.md` (gitignored), follows an immutable schema. Do not add new fields. +- **`decisions.jsonl`** — append-only JSONL. Never edit past entries. --- diff --git a/README.md b/README.md index 46f75d3..fa7461c 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,89 @@ # Lead Protocol -**Operational continuity protocol for AI agents** — vendor-agnostic, file-based, and easy to audit. +**A shift-change logbook for your AI coding assistants.** -> The missing layer between agent instructions (AGENTS.md) and agent memory (mem0). +When one AI session ends, it writes down what it did, what's left, and why it made the calls it made. The next session — even a different tool, even days later — reads that and picks up where the last one stopped. Nothing forgotten, nothing re-explained. -> Current version: **2.0.1** +> Current version: **2.0.2** --- ## The problem -When multiple AI agents (Claude Code, Cursor, Codex, Antigravity, Windsurf) work on the same codebase — across different sessions, tools, and LLMs — there is no standard way to: +You've probably hit this: you spend an afternoon working through a problem with an AI assistant, close the chat, and the next day it remembers none of it. Open a different tool — Claude Code instead of Cursor — and you start from zero again. Ask it later *why* it made some change, and there's no record. -- **Hand off state** from one agent session to the next -- **Audit decisions** made by agents with rationale -- **Recover from interrupted sessions** without losing context -- **Coordinate concurrent agents** operating on the same repo -- **Consult a peer agent mid-session** without copy-pasting context +When more than one AI assistant works on the same project — across different days, tools, and people — there's no shared place for them to leave notes for each other. So context gets lost, decisions go unexplained, and interrupted work is hard to resume. -Existing solutions solve adjacent problems: +Lead Protocol gives every assistant the same simple habit: **read the notes before you start, leave notes before you stop.** + +
+For developers: where this sits relative to AGENTS.md, mem0, and LangGraph + +Phrased technically, the gap is the *operational state layer* — what was done, what's pending, who decided what, who is live right now, and how to recover. Existing tools solve adjacent problems, not this one: - **AGENTS.md / spec-kit** tell agents *what to know* about a project (instructions layer) - **mem0 / engram** remember *what happened* in the past (memory layer, DB-backed) - **LangGraph / CrewAI** orchestrate agents *in real time* (runtime layer) -**Nobody solves the operational state layer** — what was done, what's pending, who decided what, who is live right now, and how to recover. +Lead Protocol is vendor-agnostic, file-based, and git-native: the state lives as plain files committed alongside your code, so it is diffable, reviewable, and auditable like any other part of the repo. + +
## The solution -Lead Protocol defines a set of structured files committed to your project — a per-pair `handoff.md` with a strict schema, an append-only `decisions.jsonl` audit trail, a curated `JOURNAL.md` timeline and queryable `LESSONS.md`, rules for takeover and recovery, a concurrent-session registry, and a three-layer separation (framework / project / actor × agent). Any agent that can read text files can use it. No runtime, no API, no vendor dependency. +Lead Protocol is a set of structured files committed to your git repository: + +- **`handoff.md`** — current state: what's done, what's in progress, what's blocked +- **`decisions.jsonl`** — append-only audit trail: why each important decision was made +- **`JOURNAL.md`** — curated timeline of structurally significant deliveries +- **`LESSONS.md`** — mistakes not to repeat, searchable by tag -This release is the file-based protocol scaffold. A CLI and MCP server are planned, but you do not need either one to use Lead Protocol today. +Any agent that can read text files can use it. No runtime, no database, no API keys — it's just files in your git repo. A CLI and MCP server are on the roadmap, but you never need them to use Lead Protocol today. -## Where it fits +In practice, the whole protocol is a single folder of markdown and JSON files dropped into your repository: + +``` +your-project/ +├── .agents/ +│ ├── CORE_RULES.md # Rules index + essential contracts (read first) +│ ├── PROTOCOL_RULES.md # Framework kernel (substrate-agnostic, upgradable) +│ ├── PROJECT_RULES.md # Your project's identity and context — edit this +│ ├── JOURNAL.md # Curated timeline of structurally significant deliveries +│ ├── LESSONS.md # Project-level lessons (append-at-tail, grep by tag) +│ ├── decisions.jsonl # Append-only audit trail (one JSON object per line) +│ ├── AGENTS_MAP.md # Tool-signature → agent-slug map (maintainer-managed) +│ ├── modules/ # Opt-in extension rule files +│ │ ├── README.md # Index of available modules +│ │ ├── git-substrate.md # Branching + PR + README-sync + .gitignore baseline +│ │ └── meta-repo.md # IDE/template duality + promotion lifecycle +│ ├── schemas/ +│ │ ├── handoff.schema.json # Validates parsed handoff.md +│ │ └── decisions.entry.schema.json # Validates one decisions.jsonl line +│ ├── scripts/ +│ │ ├── validate_state.py # Schema validator +│ │ ├── migrate_to_v2.py # v1.x → v2.0.0 migration tool +│ │ ├── conftest.py # Pytest config +│ │ └── test_validate_state.py # Validator tests +│ ├── checkpoints/ # Cross-agent coordination snapshots (shared) +│ ├── sessions/ +│ │ └── active_sessions.md # Concurrent session registry +│ └── local/ # ← gitignored — per (actor, agent) state +│ └── // +│ ├── handoff.md # Current operational state for this pair +│ ├── tasks/TASK.md # TODO for the active session +│ ├── activity.log # Per-pair raw activity log +│ └── lessons.md # Personal lessons for this pair +├── .gitignore # Ignores .agents/local/ +├── CLAUDE.md # Pointer for Claude Code +└── AGENTS.md # Pointer for other agents +``` + +The bundled Python scripts are validation and migration helpers — you do not need them to get started. + +
+For developers: where Lead Protocol sits in the agent stack + +Lead Protocol fills the operational-state slot in the broader agent stack: ``` ┌─────────────────────────────────────────────┐ @@ -52,10 +103,12 @@ This release is the file-based protocol scaffold. A CLI and MCP server are plann └─────────────────────────────────────────────┘ ``` +
+ ## Quick start ```bash -# Clone or download a specific release — never install from main +# Clone a specific release — never install from main git clone --branch v2.0.1 --depth 1 https://github.com/mmilanez/lead-protocol.git /tmp/lp # Copy the scaffold into your project @@ -71,7 +124,7 @@ cd your-project python .agents/scripts/validate_state.py ``` -That's it. Read the [operational manual](.agents/modules/README.md) or the sections below to understand how agents use the protocol inside your project. +That's it. Read the sections below or browse [`.agents/CORE_RULES.md`](.agents/CORE_RULES.md) to understand how agents use the protocol inside your project. ## Installing a specific version @@ -82,18 +135,7 @@ Available versions are listed on the [Releases page](https://github.com/mmilanez - **`vX.Y.Z`** (no suffix) — stable release, recommended for production use - **`vX.Y.Z-alpha.N` / `-beta.N` / `-rc.N`** — pre-releases, for preview and testing only -### Option 1 — clone a specific version - -```bash -git clone --branch v2.0.1 --depth 1 https://github.com/mmilanez/lead-protocol.git /tmp/lp -cp -R /tmp/lp/.agents your-project/.agents -cp /tmp/lp/CLAUDE.md your-project/CLAUDE.md -cp /tmp/lp/AGENTS.md your-project/AGENTS.md -cd your-project -python .agents/scripts/validate_state.py -``` - -### Option 2 — download the release archive +### Alternative — download the release archive On the [Releases page](https://github.com/mmilanez/lead-protocol/releases), pick a version and download the `Source code (zip)` or `(tar.gz)` asset. Extract and copy the files into your project as shown in Quick start. @@ -101,7 +143,7 @@ For Windows PowerShell, use equivalent `Copy-Item` commands and run the same val ### Checking which version you have -The version is recorded inside `.agents/PROTOCOL_RULES.md`. Compare against the [Version history](#version-history) table below. +`.agents/PROTOCOL_RULES.md` records the **kernel** version (the framework rules). A patch release may leave the kernel untouched — for example, release `2.0.1` ships kernel `2.0.0` because it only fixed tooling and docs. So the kernel version is a floor, not the release number. The exact release you installed is the one named in the top entry of [`CHANGELOG.md`](CHANGELOG.md); compare it against the [Version history](#version-history) table below. ### Release notes and migration @@ -110,48 +152,6 @@ The version is recorded inside `.agents/PROTOCOL_RULES.md`. Compare against the --- -## What gets installed - -``` -your-project/ -├── .agents/ -│ ├── CORE_RULES.md # Rules index + essential contracts (read first) -│ ├── PROTOCOL_RULES.md # Framework kernel (substrate-agnostic, upgradable) -│ ├── PROJECT_RULES.md # Your project's identity and context — edit this -│ ├── JOURNAL.md # Curated timeline of structurally significant deliveries -│ ├── LESSONS.md # Project-level lessons (append-at-tail, grep by tag) -│ ├── decisions.jsonl # Append-only audit trail (one JSON object per line) -│ ├── AGENTS_MAP.md # Tool-signature → agent-slug map (maintainer-managed) -│ ├── modules/ # Opt-in extension rule files -│ │ ├── README.md # Index of available modules -│ │ ├── git-substrate.md # Branching + PR + README-sync + .gitignore baseline -│ │ └── meta-repo.md # IDE/template duality + promotion lifecycle -│ ├── schemas/ -│ │ ├── handoff.schema.json # Validates parsed handoff.md -│ │ └── decisions.entry.schema.json # Validates one decisions.jsonl line -│ ├── scripts/ -│ │ ├── validate_state.py # Schema validator -│ │ ├── migrate_to_v2.py # v1.x → v2.0.0 migration tool -│ │ ├── conftest.py # Pytest config -│ │ └── test_validate_state.py # Validator tests -│ ├── checkpoints/ # Cross-agent coordination snapshots (shared) -│ ├── sessions/ -│ │ └── active_sessions.md # Concurrent session registry -│ └── local/ # ← gitignored — per (actor, agent) state -│ └── // -│ ├── handoff.md # Current operational state for this pair -│ ├── tasks/TASK.md # TODO for the active session -│ ├── activity.log # Per-pair raw activity log -│ └── lessons.md # Personal lessons for this pair -├── .gitignore # Ignores .agents/local/ -├── CLAUDE.md # Pointer for Claude Code -└── AGENTS.md # Pointer for other agents -``` - -Any agent that can read text files can work with the protocol. No runtime, no API, no vendor dependency. The bundled Python scripts are only validation and migration helpers. - ---- - ## Three-layer state model Every file under `.agents/` belongs to exactly one of three layers: @@ -162,14 +162,21 @@ Every file under `.agents/` belongs to exactly one of three layers: | **Project** | Your project | Changes with project evolution | Yes — versioned with the repo | | **Actor × Agent** | One human operator running one AI agent | Changes every session | **No** — gitignored, one folder per pair | +
+Why the pair (actor × agent) is the unit of concurrency + The smallest unit that owns volatile state is the pair `(actor, agent)`, not the actor alone. Claude Code, Codex, Gemini, and Cursor operated by the same human each get their own `local///`. That is what makes cross-agent interchange in the same project viable — agents never overwrite each other's handoff. Full detail: `.agents/PROTOCOL_RULES.md §P3 — Three-layer state model`. +
+ --- ## How agents boot in your project +> You don't run these steps — your AI agent does, automatically, the moment it reads `CLAUDE.md`. This section explains what's happening under the hood. + Every compliant agent reads, in order: 1. `.agents/CORE_RULES.md` — index + essential contracts. @@ -210,8 +217,14 @@ Patch bumps (Z) never break anything. Minor bumps (Y) may introduce new features | Version | Highlights | |---|---| -| **2.0.1** | Patch from first external consumer feedback. `migrate_to_v2.py --dry-run` now accepted (was documented but rejected by argparse); pristine `LESSONS.md` scaffold no longer false-positives the rerun-safety guard; `docs/MIGRATION-v2.md` Step 3 rewritten with a prominent agent-driven callout on `--yes` and a warning on `--agent` slug seeding pair-local continuity. No kernel or schema changes. | -| **2.0.0** | **Three-layer state model (Framework / Project / Actor × Agent).** Structural major. New files: `JOURNAL.md`, `LESSONS.md`, `AGENTS_MAP.md`. `decisions.json` (JSON array) replaced by `decisions.jsonl` (one object per line, append-only). `handoff.md` relocates to `local///handoff.md`. New `migrate_to_v2.py` migration tool. Six-step baseline boot order. `PROTOCOL_RULES.md` loads on demand via `§P-Access`. | +| **2.0.1** | Patch from first external consumer feedback. `migrate_to_v2.py --dry-run` now accepted; pristine `LESSONS.md` scaffold no longer false-positives the rerun-safety guard; `docs/MIGRATION-v2.md` Step 3 rewritten with agent-driven callout and `--agent` slug warning. No kernel or schema changes. | +| **2.0.0** | **Three-layer state model (Framework / Project / Actor × Agent).** New files: `JOURNAL.md`, `LESSONS.md`, `AGENTS_MAP.md`. `decisions.json` replaced by `decisions.jsonl` (append-only). `handoff.md` relocates to `local///handoff.md`. New `migrate_to_v2.py` migration tool. Six-step baseline boot order. | + +
+Earlier versions (v1.0.0 – v1.9.1) + +| Version | Highlights | +|---|---| | **1.9.1** | Template cosmetic pass — clarifies opt-in nature of pre-commit tooling, adds `scripts/README.md`, reframes validation section so local ad-hoc validation is the default path. No framework rules changed. | | **1.9.0** | **Substrate-agnostic kernel + opt-in modules.** `PROTOCOL_RULES.md` rewritten as kernel (§P1–§P7, new §P9 module contract); git/PR/README-sync rules extracted to `modules/git-substrate.md`; meta-repo promotion (former §P8) relocated to `modules/meta-repo.md`. | | **1.8.3** | CI state validation workflow — GitHub Action that runs `validate_state.py` on every PR. | @@ -226,6 +239,8 @@ Patch bumps (Z) never break anything. Minor bumps (Y) may introduce new features | **1.3.0** | §P6 cross-repo references + §P7 private vs shared context separation. | | **1.0.0** | Initial protocol: handoff, decisions, takeover, recovery, authority hierarchy. | +
+ ## Roadmap | Priority | Component | Status |