# 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:

```bash
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:

```bash
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.