Skip to content

feat(cli): add an update command; re-running init overwrites project-layer files #25

Description

@leonardobuares

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

  1. 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.
  2. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions