docs(playbook): add reintegration (consumer-adoption) section

[kyle-sexton]

What

Adds the missing back-half of the plugin lifecycle to the migration playbook. The doc covered migrate → publish but stopped there; reintegration — a consumer repo retiring its in-repo hook and adopting the published plugin — is the pattern that repeats for every port, and it was undocumented.

The new section is general and reusable, grounded in the verified biome-format ↔ medley audit:

• The plugin stays generic; the consumer's own seams restore its specifics — kill-switch env, CLAUDE.md/rules, and especially the telemetry sink. The key insight: the plugin emits the generic telemetry envelope to HOOK_TELEMETRY_SINK, and the consumer's sink translates it into the consumer's local observability shape. A consumer whose prior hook used a different status/identity (e.g. status=error on a violation, a legacy hook name) restores that contract in its own sink — after verifying how its observability actually keys events (status vs derived exit_code/findings) — not by changing the plugin.
• A cutover checklist (marketplace registration, kill-switch rewire, remove the in-repo hook + its test, verify the hook fires and the hard gate is untouched).
• The bootstrap-direction caveat: don't flip a still-source repo to consumer incidentally.

Context

medley's biome-format reintegration is deferred — medley stays the harvest source for now — so this PR captures the reusable pattern without touching any consumer. Docs-only.

Lint lanes (markdownlint, typos, editorconfig) pass locally.

🤖 Generated with Claude Code

[claude]

Claude finished @kyle-sexton's task in 1m 25s —— View job

---

Review

• Gather context and read changed file
• Read full playbook for coherence check
• Verify technical accuracy of claims
• Post review findings

---

The section is well-positioned and the core mental model (plugin stays generic, consumer's seams restore specifics, telemetry sink as the translation layer) is exactly right. Four issues worth flagging, ordered by severity.

---

1. Cutover checklist step order creates a coverage gap (medium)

Steps 3 and 4 are in the wrong order for safe cutover:

3. Remove the in-repo hook's settings.json registration and delete the hook script and its test.
4. Verify the plugin hook fires…

permalink

Deleting before verifying means there's a window where neither hook is active and the only signal is a missing test. The standard "blue-green" approach is: verify the replacement works first, then remove the old one. Swapping to verify → delete eliminates the gap with no other change needed. Fix this →

---

2. Fresh-docs mandate — enabledPlugins field name is unverified (medium)

The repo's CLAUDE.md is explicit: "Before ANY change to this repo… WebFetch the relevant page(s)… If a fact is not confirmed from a fetched page this session, treat it as unverified and say so." The playbook intro echoes this with its 2026-06-22 verification date.

The new section introduces the field name enabledPlugins (checklist step 1, line 137) — a schema claim that wasn't in the doc on 2026-06-22, so it wasn't covered by that verification. Per the mandate this needs a fresh fetch against https://code.claude.com/docs/en/plugin-marketplaces (or the settings schema) before merge, and if confirmed, the intro's verification date should be updated to 2026-06-29.

---

3. Verification step 4 doesn't include the telemetry sink (low)

The section spends the most words on the telemetry sink as the critical seam, but the verification step only checks that the hook fires and hard gate is intact:

Verify the plugin hook fires (edit a governed file, confirm format/lint + surfaced findings), and that the consumer's hard gate (commit hooks, CI) is untouched…

line 143-144

Worth adding a beat here: "…and that the telemetry sink receives the expected envelope" — otherwise a broken remap goes undetected until observability is needed.

---

4. Minor — "its ported plugins" is ambiguous (low)

…ideally once its ported plugins can move together.

line 149

"its" could refer to the plugin or the repo. "the repo's ported plugins" reads unambiguously.

---

Overall: the section is substantively correct and fills a real gap in the lifecycle docs. Items 1 and 2 are worth addressing before merge; 3 and 4 are low-priority polish.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9756dd92d3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 3m 19s —— View job

---

Review

• Gather context
• Read the updated MIGRATION-PLAYBOOK.md
• Diff PR changes vs origin/main
• Check whether prior review findings were addressed
• Verify Codex P2 finding against hook source
• Post final review findings

---

All four findings from the prior review are addressed in the follow-up commit. One issue introduced in the original diff — flagged by Codex but not by the prior review — remains open.

---

Prior review: all four findings resolved

#	Severity	Finding	Status
1	Medium	Step order: delete before verify	✅ Swapped — step 3 is now "Verify before retiring", step 4 is delete
2	Medium	enabledPlugins unverified against fresh docs	✅ Intro updated with 2026-06-29 verification against discover-plugins guide
3	Low	Telemetry sink missing from verification step	✅ Added: "the telemetry sink receives the expected envelope…"
4	Low	"its ported plugins" ambiguous	✅ Changed to "the repo's ported plugins"

---

Remaining issue: "the plugin already reads" is incorrect for hook-based plugins (medium)

The reintegration section (line 122) says:

Project conventions → the consumer's CLAUDE.md / .claude/rules, which the plugin already reads.

This claim is inaccurate for hook-centric plugins. The extensibility model table (line 39) is precise about this — it says "The skill reads the consuming project's own context and rules." Skills run in Claude's model context and do receive CLAUDE.md. Hook scripts do not. biome-format.sh and bash-lint.sh read env vars and file-based config (biome.json, .shellcheckrc, etc.) — not CLAUDE.md. A consumer who routes a project convention to CLAUDE.md for a hook-based plugin will have it silently ignored.

The fix is either to scope the claim to skill components of the plugin, or to note that for hook-based plugins, conventions route through userConfig/env rather than CLAUDE.md. Something like:

Project conventions → the consumer's CLAUDE.md / .claude/rules (for the plugin's skill/agent components, which receive model context); for hook scripts, use userConfig or env vars instead.

Or, if this section is explicitly targeted at hook cutover: drop the CLAUDE.md bullet and let the kill-switch env var bullet carry it. Fix this →

---

Overall: the follow-up commit is solid — every prior finding has a clean fix. The one remaining item is the hook-vs-skill distinction on CLAUDE.md; it's medium priority because a consumer who follows the current guidance for a hook-based plugin would silently lose the convention with no error.

[kyle-sexton]

Thanks — all four addressed in 69d4772:

#1 (cutover step order, medium) — Fixed. Reordered to verify-before-retire (blue-green): step 3 now confirms the plugin works with the old hook still in place, step 4 retires the old hook only after. Added a note that the brief both-hooks overlap is harmless since formatting is idempotent.

#2 (fresh-docs mandate, medium) — Verified this session. Confirmed extraKnownMarketplaces + enabledPlugins as project settings.json fields against the discover-plugins "Configure team marketplaces" guide (which also documents the trust-prompt behavior I described). Cited the 2026-06-29 verification in the intro provenance line rather than bumping the whole doc's date (which would falsely imply every claim was re-verified).

#3 (verify the sink, low) — Folded into the reordered verify step: "the telemetry sink receives the expected envelope (so a broken remap is caught now, not when observability is next needed)."

#4 ("its" ambiguous, low) — Changed to "the repo's ported plugins."

Lint lanes green.

[kyle-sexton]

Fixed in 7358e0b — you're right, and it's an important distinction for a section whose worked example is a hook. Scoped the bullet: for hook plugins, project conventions route through the consumer's own file-based tool config (biome.json, .shellcheckrc, .editorconfig) that the hook already reads — and noted explicitly that CLAUDE.md / .claude/rules reach only a plugin's skill/agent components (model context), not hook scripts. This actually sharpens the section, since file-based config is the real convention seam for these plugins.

[claude]

Claude finished @kyle-sexton's task in 1m 33s —— View job

---

Review

• Gather context
• Read current MIGRATION-PLAYBOOK.md and diff vs origin/main
• Verify prior review findings are resolved (including 7358e0b hook-vs-skill fix)
• Post final review findings

---

All findings across both prior review rounds are resolved. This is a clean pass.

---

All prior findings — resolved

Round	#	Severity	Finding	Status
1	1	Medium	Step order: delete before verify	✅ Swapped — verify-before-retire with idempotency note
1	2	Medium	enabledPlugins unverified against fresh docs	✅ Verified 2026-06-29, provenance updated in intro
1	3	Low	Telemetry sink missing from verification step	✅ Added to step 3
1	4	Low	"its ported plugins" ambiguous	✅ "the repo's ported plugins"
2	5	Medium	"the plugin already reads" — inaccurate for hook-based plugins	✅ Fixed in 7358e0b (see below)

---

7358e0b fix is accurate

The corrected bullet at line 122–125:

Project conventions → for a hook plugin, the consumer's own tool config files that the hook already reads (biome.json, .shellcheckrc, .editorconfig, …) — that is where these plugins pick up project conventions, not CLAUDE.md. (CLAUDE.md / .claude/rules reach only a plugin's skill/agent components, which run in Claude's model context; hook scripts see only env vars and file-based config.)

This is technically correct and consistent with the extensibility model table (line 39), which already scoped CLAUDE.md/rules to skills. The fix also eliminates the silent-failure risk: a consumer following the old guidance would have routed a convention to CLAUDE.md and had it silently ignored by the hook script.

---

Overall: the section is substantively correct, every review finding has a clean fix, and the hook-vs-skill distinction is now precise and consistent with the rest of the playbook. Ready to merge.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7358e0b314

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 1m 38s —— View job

---

Review

• Gather context
• Read current MIGRATION-PLAYBOOK.md and diff vs origin/main
• Verify 4f47218 fix for concurrent hook race (Codex P2)
• Post final review findings

---

4f47218 correctly addresses the Codex P2 finding. Clean pass.

---

4f47218 fix is accurate

The corrected step 3 at lines 147–156 replaces the prior "idempotent overlap is harmless" claim with a disable-before-verify procedure. The fix is technically correct on all three counts:

• Concurrent execution model — "matching PostToolUse hooks run concurrently" is accurate per the hooks reference, and the last-writer-wins / doubled-telemetry consequences are correctly described.
• Safe procedure — disable the old hook (kill switch or comment out its registration, not delete) → verify the plugin → delete only after. The "or" is important: after step 2 rewires the env var name, the old hook's env-var kill switch may no longer be set in settings.json; commenting out the registration is the always-reliable path.
• Blue-green property preserved — the plugin is active throughout (enabled in step 1), the old hook is recoverable if verification fails ("re-enable the old hook"), and "there is never a no-hook gap" is correct given the sequencing.

---

Full finding history — all resolved

Round	#	Severity	Finding	Status
1	1	Medium	Step order: delete before verify	✅ Swapped — verify-before-retire
1	2	Medium	enabledPlugins unverified against fresh docs	✅ Verified 2026-06-29, provenance updated
1	3	Low	Telemetry sink missing from verification step	✅ Added to step 3
1	4	Low	"its ported plugins" ambiguous	✅ "the repo's ported plugins"
2	5	Medium	"the plugin already reads" — inaccurate for hook-based plugins	✅ Fixed in 7358e0b — hook plugins read file-based tool config, not CLAUDE.md
Codex P2	6	Medium	Concurrent hook race — "idempotent overlap is harmless"	✅ Fixed in 4f47218 — disable-before-verify, no concurrent mutation

---

Overall: every finding across all review rounds has a clean fix. The section is substantively correct, internally consistent with the extensibility model table, and the cutover procedure is now safe. Ready to merge.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4f4721871d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 1m 25s —— View job

---

Review

• Gather context and read current MIGRATION-PLAYBOOK.md
• Diff PR changes vs origin/main
• Verify latest commit (df82e0f) addresses the two new Codex P2 findings
• Post final review findings

---

df82e0f correctly addresses both Codex P2 findings raised against 4f47218. Clean pass.

---

df82e0f fixes are accurate

Codex P2 / "Avoid recommending comments in settings JSON"

The old step 3 offered "flip its kill switch or comment out its settings.json registration" as two equally valid paths. The new text at lines 151–153:

disable the in-repo hook by setting its kill-switch env var to "false" (or, if it has none, removing its registration entry — settings.json is JSON, so toggling the value or removing the entry is the edit, never a // comment)

✅ Correct. Standard JSON does not support // comments; a comment would make the file unparseable and silently drop all settings, including the plugin enablement from step 1. The fix names both valid alternatives (toggle value, remove entry) and explicitly rules out comments.

Codex P2 / "Disable the plugin before falling back"

The old failure path said "re-enable the old hook; the plugin stays active throughout" — which would have recreated the concurrent two-formatter race that the rest of step 3 explicitly warns against. The new text at lines 157–159:

If verification fails, disable the plugin first, then re-enable the old hook (always flip one off as you turn the other on) and debug before retrying — so the two never run together and there is never a no-hook gap.

✅ Correct. The rollback sequence now obeys the same "exactly one active at a time" invariant as the forward path. The "always flip one off as you turn the other on" phrasing generalizes the rule cleanly across both paths.

---

Full finding history — all resolved

Round	#	Severity	Finding	Status
1	1	Medium	Step order: delete before verify	✅ Swapped in 69d4772
1	2	Medium	enabledPlugins unverified against fresh docs	✅ Verified 2026-06-29, provenance updated
1	3	Low	Telemetry sink missing from verification step	✅ Added to step 3
1	4	Low	"its ported plugins" ambiguous	✅ "the repo's ported plugins"
2	5	Medium	"the plugin already reads" — inaccurate for hook-based plugins	✅ Fixed in 7358e0b
Codex P2	6	Medium	Concurrent hook race — "idempotent overlap is harmless"	✅ Fixed in 4f47218
Codex P2	7	P2	"comment out its registration" — // is invalid JSON	✅ Fixed in df82e0f
Codex P2	8	P2	Fallback re-enables old hook while plugin stays active — recreates race	✅ Fixed in df82e0f

---

Overall: every finding across all review rounds has a clean fix. The "exactly one hook active at a time" invariant now holds on both the happy path and the rollback path, the JSON validity constraint is explicit, and the section is technically consistent throughout. Ready to merge.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: df82e0f6e6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 1m 39s —— View job

---

Review

• Gather context
• Read current MIGRATION-PLAYBOOK.md and diff vs origin/main
• Verify latest commit (56bebfc) addresses the Codex P2 headless install finding
• Post final review findings

---

56bebfc correctly addresses the Codex P2 finding about the headless/CI install gap. Verified against the discover-plugins guide (https://code.claude.com/docs/en/discover-plugins, fetched 2026-06-29).

---

56bebfc fix is accurate

The updated step 1 (lines 142–147):

Register the marketplace in the consumer's extraKnownMarketplaces and enable the plugin in enabledPlugins (project settings.json, so clones inherit it on trust — the interactive trust prompt both registers and installs the enabled plugin). Headless/CI has no such prompt, and registering a marketplace does not install its plugins, so do both explicitly: claude plugin marketplace add <repo> then claude plugin install <plugin>@<marketplace> --scope project — otherwise the marketplace is known but the plugin is absent, and step 3's verify edit would run with no plugin hook.

Three claims, all verified against fresh docs:

• "registering a marketplace does not install its plugins" — confirmed. The docs' two-step model is explicit: "adding registers the catalog … No plugins are installed yet." ✓
• "the interactive trust prompt both registers and installs the enabled plugin" — confirmed. The "Configure team marketplaces" section: "When team members trust the repository folder, Claude Code prompts them to install these marketplaces and plugins." ✓
• Command syntax — claude plugin install <plugin>@<marketplace> --scope project matches the documented CLI form exactly. ✓

The failure mode is also correctly described: marketplace known but plugin absent means step 3's verify edit fires with no plugin hook active — precisely the gap the Codex finding flagged.

---

Full finding history — all resolved

Round	#	Severity	Finding	Status
1	1	Medium	Step order: delete before verify	✅ Swapped in 69d4772
1	2	Medium	enabledPlugins unverified against fresh docs	✅ Verified 2026-06-29, provenance updated
1	3	Low	Telemetry sink missing from verification step	✅ Added to step 3
1	4	Low	"its ported plugins" ambiguous	✅ "the repo's ported plugins"
2	5	Medium	"the plugin already reads" — inaccurate for hook-based plugins	✅ Fixed in 7358e0b
Codex P2	6	Medium	Concurrent hook race — "idempotent overlap is harmless"	✅ Fixed in 4f47218
Codex P2	7	P2	"comment out its registration" — // is invalid JSON	✅ Fixed in df82e0f
Codex P2	8	P2	Fallback re-enables old hook while plugin stays active — recreates race	✅ Fixed in df82e0f
Codex P2	9	P2	Headless cutover missing explicit plugin install step	✅ Fixed in 56bebfc

---

Overall: every finding across all review rounds has a clean fix. The cutover checklist is now correct for both interactive and headless/CI consumers, the "exactly one hook active at a time" invariant holds on both the happy path and rollback path, and all schema/CLI claims are verified against fresh docs. Ready to merge.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 56bebfca83

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Use the hook's documented kill switch

This assumes the env var is derived from the plugin manifest name, but markdown-formatter already disproves that: its manifest name is markdown-formatter, while the hook calls hook::check_enabled "MARKDOWN_FORMAT" and the README documents HOOK_MARKDOWN_FORMAT_ENABLED. A consumer following this step would set/flip HOOK_MARKDOWN_FORMATTER_ENABLED, which the hook never reads, so the plugin could remain active during cutover or rollback; point to each plugin's documented kill switch instead of deriving it from the plugin name.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Reload the plugin before verifying it

In an existing Claude Code session, the headless install/enabled path here is followed immediately by step 3's edit, but installed/enabled plugins are not activated until the session reloads them; the official Discover plugins guide (https://code.claude.com/docs/en/discover-plugins) says, "After installing, run /reload-plugins to activate the plugin," and its CLI section repeats this for install/enable/disable. Without an explicit /reload-plugins or restart before the verify edit, the old hook can be disabled while the plugin hook is still absent, causing a false fallback or a no-hook window.

Useful? React with 👍 / 👎.