From e93f2666fdedff7664c03856f52978eb4543292b Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Wed, 24 Jun 2026 14:02:04 -0400
Subject: [PATCH] docs(playbook): document the local plugin development loop
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The playbook covered first-publish validation (the migration gate's
--plugin-dir step) but not how to iterate on an already-shipped plugin
against a local clone. Add a "Local development loop" section: load the
working copy with `claude --plugin-dir ./plugins/<name>` (the local copy
takes session precedence over the installed same-name plugin), edit then
`/reload-plugins` to pick up on-disk changes without a restart, commit, and
let consumers pull via `/plugin marketplace update`.

Key point for the consumer seam: local development never requires switching
a consumer's tracked `extraKnownMarketplaces` source — the published remote
registration stays put; `--plugin-dir` overrides it for the session only.

Verified 2026-06-24 against the official plugins guide (canonical URLs in
CLAUDE.md), per this repo's fresh-docs mandate.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/MIGRATION-PLAYBOOK.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/MIGRATION-PLAYBOOK.md b/docs/MIGRATION-PLAYBOOK.md
index 5e26acdbc..9b2843b0f 100644
--- a/docs/MIGRATION-PLAYBOOK.md
+++ b/docs/MIGRATION-PLAYBOOK.md
@@ -81,6 +81,30 @@ For each skill/hook/agent being migrated:
     2026-06-23). Then run `claude plugin validate --strict <repo-root>` to validate the **catalog manifest
     itself** — a bad entry surfaces only there, not in per-plugin validation. Document the plugin in the README.
 
+## Local development loop
+
+For a plugin that already ships here, iterate against your local clone without re-publishing and
+without changing any consumer's marketplace registration. `--plugin-dir` loads a plugin straight from
+a directory; when its `name` matches an installed marketplace plugin, **the local copy takes
+precedence for that session**, so you exercise working-tree edits against the installed copy without
+uninstalling it (verified 2026-06-24).
+
+```shell
+# from this repo root — point at the plugin directory, not the marketplace root
+claude --plugin-dir ./plugins/<name>
+```
+
+- **Edit, then `/reload-plugins`** to pick up changes without restarting — it reloads skills, agents,
+  hooks, and plugin MCP/LSP servers, reading the files on disk, so no commit or reinstall is needed.
+- **Session-scoped and non-destructive.** The override lasts only for that session and never edits a
+  consumer's `extraKnownMarketplaces`; the published registration stays on its GitHub remote. The lone
+  exception: `--plugin-dir` cannot override a plugin that *managed* settings force-enable or
+  force-disable.
+- **Trust.** A locally loaded plugin carries the same trust considerations as any source — only load
+  directories you control.
+- **Then ship.** Run `claude plugin validate` before opening a PR; after merge, consumers pull the
+  change with `/plugin marketplace update melodic-software`, gated by the `version` bump in `plugin.json`.
+
 ## What to wait on / avoid for now
 
 - Don't pre-build cross-plugin `dependencies` graphs until two plugins genuinely share a need.