3.7 KiB
| id | date | status | supersedes | superseded-by | affected-paths | affected-components | migration_confidence | migration_source |
|---|---|---|---|---|---|---|---|---|
| 0018 | 2026-07-03 | Accepted | medium | docs/memory-system/03-architecture-decisions.md### ADR-018 — Plugin renames must update the marketplace manifest, not just the directory and settings.json |
0018 — Plugin renames must update the marketplace manifest, not just the directory and settings.json
Context
The memory plugin directory was renamed to os-vault (git rename,
plugins/memory/ → plugins/os-vault/), the ~/.claude/plugins/os-vault symlink was
updated, and settings.json's enabledPlugins was flipped to os-vault@local-plugins.
Despite this, no os-vault slash commands (skills) were available in-session. Root cause:
the local-plugins marketplace manifest (~/.claude/plugins/.claude-plugin/marketplace.json)
— which explicitly lists each plugin's name/source rather than auto-discovering the
directory — still declared only memory/./memory, and installed_plugins.json still held
a stale install record for memory@local-plugins. Hooks kept firing throughout (they're
wired by absolute path directly in settings.json, bypassing plugin resolution entirely),
which masked the break — everything looked healthy except the skills/slash-commands.
Decision
A local-plugin rename/move is a three-file operation: (1) the plugin directory
or symlink, (2) the marketplace manifest entry (name + source), (3) settings.json
enabledPlugins. After all three, run claude plugin marketplace update <marketplace> to
re-validate, claude plugin install <new>@<marketplace> to create the new install record,
and claude plugin uninstall <old>@<marketplace> to drop the stale one — then verify with
claude plugin list and claude plugin details <new>@<marketplace> (skills/agents/hooks
inventory). Documented as a standing procedure in CLAUDE.md under "Renaming or moving a
local plugin."
- Rationale: The marketplace manifest is the actual source of truth for what plugins exist
under a directory-source marketplace — the directory listing itself is not consulted for
plugin identity. Because hooks are independently wired by path, they give a false signal that
the plugin is fully operational; skill/slash-command registration must be checked separately
via
claude plugin details.
Consequences
Renaming a local plugin is now a documented three-file operation (directory/symlink, marketplace manifest entry, settings.json enabledPlugins) followed by marketplace update, install of the new record, and uninstall of the stale one, verified via claude plugin details. This was necessitated because the memory→os-vault rename left skills unavailable despite hooks still firing, since hooks are wired by absolute path and gave a false signal of full functionality while the marketplace manifest (the actual source of plugin identity) still pointed at the old name.
Alternatives rejected
Rely on directory listing / auto-discovery — not how
local-plugins (a directory-source marketplace) resolves plugins; the manifest is
authoritative. Skip the install/uninstall refresh, just fix the manifest — leaves a stale
cached install record in installed_plugins.json under the old name, which is confusing and
can mask a future rename of the same kind.
- Consequences / ongoing contracts: any future rename of
os-vault(or a new local plugin) must touch the marketplace manifest, not justsettings.json.claude plugin details <plugin>@<marketplace>is the verification step to run after any plugin registration change — it surfaces the skill/agent/hook inventory that a passing hook test would not.