jared
/
cc-os
1
0
Fork 0
Code Issues 18 Pull Requests Packages Projects Releases Wiki Activity
cc-os/docs/implementation-status/operational-procedures.md

2.6 KiB
Raw Blame History

Operational procedures

Stable runbooks referenced from CLAUDE.md. Keep this file's procedures current — they are the canonical copies.

Renaming or moving a local plugin

Renaming a plugin directory under a directory-source marketplace (like local-plugins, whose source is ~/.claude/plugins itself) requires updating three places, not just the directory and settings.json:

  1. Plugin directory / symlink — the actual files (or symlink target, for plugins that live in a git repo like cc-os/plugins/os-vault/).
  2. Marketplace manifest — ~/.claude/plugins/.claude-plugin/marketplace.json (for local-plugins) lists each plugin's name and source path explicitly; this does not auto-discover from the directory listing. Update the entry to match the new name/path.
  3. settings.json enabledPlugins — the <name>@<marketplace> key must match the manifest entry from step 2.

Then refresh the plugin manager's state so it re-resolves the marketplace and drops the stale install record:

claude plugin marketplace update <marketplace-name>   # re-validates the manifest
claude plugin install <new-name>@<marketplace-name>    # creates the new install record
claude plugin uninstall <old-name>@<marketplace-name>  # drops the stale one
claude plugin list                                     # verify: new name enabled, old name gone
claude plugin details <new-name>@<marketplace-name>     # verify skills/agents/hooks resolved

Skipping step 2 is the failure mode to watch for: hooks (wired by absolute path in settings.json) keep working, masking the fact that skills/slash-commands silently stopped registering under the plugin's new name. See ADR-0018.

Editing a local plugin (cache refresh)

Plugin source edits (including SKILL.md wording, hook scripts, or CLI code) do not reach running sessions until the cache is refreshed. Claude Code caches plugins when installed, copying them to ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/. To refresh a stale cache after source edits:

bin/refresh-plugins [marketplace-names...]    # refresh all or specific local marketplaces

This uninstalls and reinstalls each plugin, forcing the cache to repopulate. See bin/refresh-plugins --help for usage. After refreshing, claude plugin details <name>@<marketplace> should show updated skill descriptions and hook counts. Directory-source marketplaces (e.g., local-plugins sourced from ~/.claude/plugins, cc-plugins sourced from ~/dev/cc-plugins) are the only ones that need manual refresh — public marketplaces auto-update.