Problem
The CLI has no way to update an existing installation to a newer protocol
release. The only path today is re-running lead-protocol init, and that path
is destructive: after the "Lead Protocol is already installed in this
directory. Overwrite protocol files?" confirmation, init runs a recursive
copy of the bundled templates over the whole .agents/ tree
(cli/src/commands/init.ts). This replaces project-layer files with blank
templates, destroying PROJECT_RULES.md, AGENTS_MAP.md, JOURNAL.md,
LESSONS.md, decisions.jsonl and sessions/active_sessions.md. In other
words, updating wipes the project's memory.
This contradicts the protocol's own three-layer state model: CORE_RULES.md
states that the framework layer "ships with the release" while the project
layer is versioned with the project, and the PROJECT_RULES.md template says
literally "Never overwritten by framework upgrades". The tooling should honor
the contract the rules define.
Proposed solution
-
A new lead-protocol update command that:
- always refreshes the framework layer (
CORE_RULES.md,
PROTOCOL_RULES.md, modules/, schemas/, scripts/) to the release
bundled with the CLI;
- never overwrites project-layer files, but creates any project-layer seed
the installation is missing (so old installs pick up new structure);
- never touches
.agents/local/;
- refreshes the
<lead-protocol> blocks in CLAUDE.md / AGENTS.md
(the tag mechanism is already idempotent) and re-checks the .gitignore
entries;
- reports every file as
updated / created / unchanged, and lists
files found under modules/, schemas/ or scripts/ that are absent
from the bundled release (leftovers or user extensions) as warnings,
without ever deleting anything;
- supports
--yes (CI) and --dry-run.
-
A guard on init: when the protocol is already installed, init refuses
and points to update. A full reinstall stays available behind
init --force, with an explicit warning listing the project-layer files
that will be lost.
Agent context
Claude Code, but the problem is agent-independent: it lives in the CLI, and
the data destroyed is the shared state every agent relies on at boot.
Alternatives considered
- Making
init layer-aware instead of adding a command: rejected, it mixes
two semantics (install vs update) in one verb and blocks update-specific
flags such as --dry-run.
- Tracking the installed version in a marker file (e.g.
.agents/VERSION):
rejected for now, content comparison gives the useful report without adding
a new file to the protocol layout.
- Deleting orphaned framework files: rejected, without a manifest of the
previously installed release it is impossible to distinguish a retired
framework file from a user extension, so the CLI never deletes.
Additional context
A PR implementing this is ready and will be linked to this issue.
Problem
The CLI has no way to update an existing installation to a newer protocol
release. The only path today is re-running
lead-protocol init, and that pathis destructive: after the "Lead Protocol is already installed in this
directory. Overwrite protocol files?" confirmation,
initruns a recursivecopy of the bundled templates over the whole
.agents/tree(
cli/src/commands/init.ts). This replaces project-layer files with blanktemplates, destroying
PROJECT_RULES.md,AGENTS_MAP.md,JOURNAL.md,LESSONS.md,decisions.jsonlandsessions/active_sessions.md. In otherwords, updating wipes the project's memory.
This contradicts the protocol's own three-layer state model:
CORE_RULES.mdstates that the framework layer "ships with the release" while the project
layer is versioned with the project, and the
PROJECT_RULES.mdtemplate saysliterally "Never overwritten by framework upgrades". The tooling should honor
the contract the rules define.
Proposed solution
A new
lead-protocol updatecommand that:CORE_RULES.md,PROTOCOL_RULES.md,modules/,schemas/,scripts/) to the releasebundled with the CLI;
the installation is missing (so old installs pick up new structure);
.agents/local/;<lead-protocol>blocks inCLAUDE.md/AGENTS.md(the tag mechanism is already idempotent) and re-checks the
.gitignoreentries;
updated/created/unchanged, and listsfiles found under
modules/,schemas/orscripts/that are absentfrom the bundled release (leftovers or user extensions) as warnings,
without ever deleting anything;
--yes(CI) and--dry-run.A guard on
init: when the protocol is already installed,initrefusesand points to
update. A full reinstall stays available behindinit --force, with an explicit warning listing the project-layer filesthat will be lost.
Agent context
Claude Code, but the problem is agent-independent: it lives in the CLI, and
the data destroyed is the shared state every agent relies on at boot.
Alternatives considered
initlayer-aware instead of adding a command: rejected, it mixestwo semantics (install vs update) in one verb and blocks update-specific
flags such as
--dry-run..agents/VERSION):rejected for now, content comparison gives the useful report without adding
a new file to the protocol layout.
previously installed release it is impossible to distinguish a retired
framework file from a user extension, so the CLI never deletes.
Additional context
A PR implementing this is ready and will be linked to this issue.