chore(migration-playbook): record adoption verdicts for unused plugin components

[kyle-sexton]

What

Adds an "Unused official plugin components — decision record (2026-07-12)" section to docs/MIGRATION-PLAYBOOK.md evaluating the three official plugin components the marketplace does not yet use:

• monitors (monitors/monitors.json / experimental.monitors)
• bin/ (executables on the Bash tool PATH)
• subagentStatusLine (plugin settings.json)

Verdicts

All three REJECT now, each with an explicit revisit trigger — evaluated against the enforcement hierarchy (default REJECT unless the value is concrete and not already covered by an existing mechanism):

• monitors — PR/CI candidate duplicates /source-control:pull-request monitor + channel-mode; collector-health value not concrete enough to adopt an experimental.* component.
• bin/ — ${CLAUDE_PLUGIN_ROOT}/scripts/ already covers plugin-owned scripts; the one live candidate (knowledge extraction tooling) is owned by publish issue #1373 — coordinated there, not duplicated.
• subagentStatusLine — purely cosmetic; does not clear the default-REJECT bar.

Zero accepted → zero implementation issues emitted (the DONE "file accepted items as issues" is satisfied vacuously).

Notes

• Facts verified fresh against upstream docs 2026-07-12 per CLAUDE.md fresh-docs mandate; record cites upstream URLs, does not recap schema/mechanism (upstream-cites rule).
• Follows the existing "Deferred surfaces — decision record" shape so the records read as one system.
• markdownlint / typos / editorconfig-checker all clean locally.

Refs melodic-software/medley#1399

---

Note

Low Risk
Documentation-only decision record with no runtime, config, or security surface changes.

Overview
Adds "Unused official plugin components — decision record (2026-07-12)" to docs/MIGRATION-PLAYBOOK.md, mirroring the existing deferred-surfaces record so adoption choices are explicit rather than silent omissions.

All three evaluated components get REJECT now under the default-REJECT bar, each with a revisit trigger and upstream doc links (no schema recap): monitors (overlap with PR monitor skills / experimental risk), bin/ (prefer ${CLAUDE_PLUGIN_ROOT}/scripts/; knowledge extraction deferred to issue #1373), and subagentStatusLine (cosmetic only). Zero accepted means no follow-up implementation issues from this pass.

^{Reviewed by Cursor Bugbot for commit 3ca0309. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_e9ded6ca-9f21-44e5-9042-40fbfe2cca02)

[claude]

Claude finished @kyle-sexton's task in 2m 15s —— View job

---

PR Review

• Gather context and read changed files
• Review the decision record content for correctness and policy alignment
• Check fresh-docs mandate compliance
• Verify formatting and structure consistency
• Post final review

---

Summary

Documentation-only PR adding a well-structured decision record for three unused official plugin components. The verdict logic is sound, the structure mirrors the existing "Deferred surfaces" record correctly, and all three REJECT decisions have clear, concrete revisit triggers. One minor precision concern and one cross-reference tension worth noting.

---

Findings

1. when: "on-skill-invoke:<skill>" syntax is unverified against current docs

Line 512–513:

scoped via `when: "on-skill-invoke:<skill>"` so it starts only on demand
rather than at session start

This when value appears nowhere else in the playbook and is not attributed to a docs page. If on-skill-invoke is a real documented when discriminant, the upstream citation should cover it — the cited URLs (#monitors, #monitor-tool) don't include an anchor to a when values table. If it's aspirational/hypothetical syntax, the revisit trigger phrasing should say so (e.g., "…scoped to run on-demand rather than at session start, once a suitable when discriminant is documented"). As written it reads as established schema that a future contributor would copy verbatim. Fix this →

2. Minor cross-reference tension with line 173

The "Shared tools and scripts seam" section already says scripts run via ${CLAUDE_PLUGIN_ROOT}/scripts/ (or bin/), treating bin/ as an established alternative path. The new decision record then says "bin/ adds only bare-command-on-PATH invocation" and rejects it. These statements aren't contradictory — the distinction (directory path vs. PATH exposure) is real and accurate — but a reader landing at line 173 after reading the new record may wonder why (or bin/) is listed as established if it was just rejected. This pre-dates this PR; the new record is correct on its own terms. Low severity, but worth a follow-up clarifying note in line 173 if the bin/-on-PATH distinction is commonly asked. Not a blocker.

---

What's Good

• Structure: Exactly matches the "Deferred surfaces — decision record" shape — date-stamped header, enforcement-hierarchy preamble, bullet-per-component, bold verdict, inline revisit trigger, upstream citation. Reads as one system.
• REJECT logic is consistently applied: All three components are evaluated against the same bar ("concrete value not already covered by an existing mechanism") and correctly fail it. The bin/ entry correctly identifies the name-collision risk and defers the one live candidate to its tracking issue rather than pre-deciding here.
• Revisit triggers are actionable: Each trigger is a specific observable condition, not "reconsider when useful" — exactly what the enforcement hierarchy requires.
• No implementation issues emitted: Zero-accepted → zero-issued is correctly stated and consistent with the record.
• Upstream citation discipline: Each entry cites the specific docs URLs it draws from without recapping schema — correct per the upstream-cites rule.
• Fresh-docs claim is appropriately scoped: "Facts verified fresh 2026-07-12" is in the preamble; the record correctly doesn't make claims beyond what can be verified from those pages.

---

One finding to address before merge; everything else is clean.

[cursor]

Stale comment

Risk: low. Not approving because Cursor Bugbot skipped (usage limit reached) and did not complete automated review. Human review is needed before merge; no reviewers were assigned because no non-author human maintainers are available on this repository.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_43d1bba0-ee97-44d2-b781-fd01b46e81f8)

[claude]

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

---

PR Review

• Gather context and read changed files
• Diff the latest commit against previous to check if prior finding was addressed
• Review the updated decision record content
• Check fresh-docs mandate compliance
• Post final review

---

Summary

The latest commit (8828ac6) directly resolves the one finding raised in the prior review. The PR is clean.

---

Finding #1 — RESOLVED

Previous finding: when: "on-skill-invoke:<skill>" syntax was unverified against current docs; the <skill> placeholder didn't match what the upstream reference shows.

Fix applied in 8828ac6:

- scoped via `when:
- "on-skill-invoke:<skill>"` so it starts only on demand rather than at session start.
+ scoped via the documented `when:
+ "on-skill-invoke:<skill-name>"` monitor field so it starts only on demand rather than at session
+ start.

Two correct changes:

1. Placeholder corrected from <skill> → <skill-name>, matching the Optional fields table at plugins-reference#monitors.
2. Added "documented … monitor field" to clearly attribute the value to the cited upstream page rather than presenting it as aspirational syntax.

The commit message confirms the sourcing: "the value is covered by the cited plugins-reference #monitors Optional fields table." The fix is precise and the surrounding upstream citations already cover this field.

---

Finding #2 — Pre-existing, non-blocking

The minor cross-reference tension between line 173 (scripts/ (or bin/)) and the new REJECT entry was noted in the prior review as low severity / not a blocker — it predates this PR and the new record is correct on its own terms. No action required here.

---

What's Good

• Finding addressed correctly and minimally — the fix changes only the two precision problems (placeholder name, attribution word), leaving the revisit trigger logic intact.
• Decision record structure is consistent — date-stamped header, enforcement-hierarchy preamble, bold verdicts, actionable revisit triggers, upstream citations without schema recap.
• REJECT logic is sound for all three components — monitors (experimental risk + existing coverage), bin/ (path collision risk, deferred to #1373), subagentStatusLine (cosmetic only).
• Zero accepted → zero follow-up issues — correctly stated.
• Fresh-docs claim is properly scoped — "Facts verified fresh 2026-07-12" in the preamble; no claims beyond what the cited pages cover.

---

Ready to merge.

[cursor]

Stale comment

Risk: low. Not approving because Cursor Bugbot skipped (usage limit reached) and did not complete automated review. Human review is needed before merge; no reviewers were assigned because no non-author human maintainers are available on this repository.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

[kyle-sexton]

Thanks — addressed:

Finding 1 (when syntax attribution): The when: "on-skill-invoke:<skill-name>" value is documented — it is the monitor Optional fields table in the plugins-reference Monitors section, which the cited #monitors anchor already covers. Fixed in 8828ac6: placeholder now matches the docs verbatim (<skill-name>) and the phrasing marks it as "the documented when monitor field", so it no longer reads as invented schema.

Finding 2 (line 173 (or bin/) tension): Left as-is — it pre-dates this PR and the two statements are on different axes (line 173 = bin/ is a valid location for plugin-owned scripts; this record rejects bin/ as a bare-command-on-PATH marketplace-wide adoption). Not reopening an out-of-scope line in a docs-only audit PR; flagging here for a future clarifying pass if the distinction proves commonly asked.

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_b597ca33-6ffd-43fa-9d0f-eb525b2fcdb5)

[claude]

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

---

PR Review

• Gather context and read changed files
• Review decision record content for correctness and policy alignment
• Check fresh-docs mandate compliance and citation accuracy
• Verify structure consistency with existing "Deferred surfaces" record
• Post final review

---

Summary

The latest trigger is a clean merge commit from main (8334bdb) — no content changes to MIGRATION-PLAYBOOK.md beyond what was already reviewed. The previously-raised finding (unverified when syntax) was resolved in 8828ac6. This is a final confirmation pass on the current state.

---

Current State — Clean

Monitors entry (lines 506–516)

• REJECT reasoning is sound: PR/CI watch duplicates existing /source-control:pull-request monitor coverage; collector-health candidate fails the concreteness bar; experimental.* schema-change risk is correctly cited.
• when: "on-skill-invoke:<skill-name>" now verbatim-matches the upstream Optional fields table and is attributed as "the documented … monitor field." Prior finding fully resolved.
• Both upstream citations present (#monitors, #monitor-tool).

bin/ entry (lines 517–525)

• REJECT scope is correctly bounded to "marketplace-wide adoption," not to bin/ as a directory concept — the distinction from line 173 (scripts/ (or bin/) as a valid location) is preserved and correct.
• Name-collision risk articulation is accurate; deferral to publish issue #1373 is the right call.
• Citation (#standard-plugin-layout) appropriate.

subagentStatusLine entry (lines 526–532)

• "Purely cosmetic / no functional capability" is the correct bar for default-REJECT; the note about Claude Code version minimum for richest inputs adds useful forward context.
• Dual citation (#subagent-status-lines, #standard-plugin-layout) is appropriate — the first covers the field's behavior, the second its placement in the manifest.

Section shape

• Date-stamped header, enforcement-hierarchy preamble, bold-verdict + bold-revisit-trigger per bullet, upstream-cite-only (no schema recap): exactly mirrors the "Deferred surfaces — decision record" above it. Reads as one system.

Zero accepted → zero implementation issues: correctly stated and consistent with three REJECTs.

---

No new findings. Ready to merge.

[cursor]

Stale comment

Risk: low. Not approving because Cursor Bugbot skipped (usage limit reached) and did not complete automated review. Human review is needed before merge; no reviewers were assigned because no non-author human maintainers are available on this repository.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_1a3d656c-9283-406f-8b92-bbddfb4ac779)

[claude]

PR Review

• Read changed file and diff
• Verify content against prior review findings
• Post final review

View job run

[cursor]

Stale comment

Risk: low. Not approving because Cursor Bugbot skipped (usage limit reached) and did not complete automated review. Human review is needed before merge; no reviewers were assigned because no non-author human maintainers are available on this repository.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_93310b52-6e30-4bc2-9a31-bf135f6dfbd9)

[claude]

Claude finished @kyle-sexton's task in 42s —— View job

---

PR Review

• Read changed file and diff
• Verify current state against prior review findings
• Post final review

---

Summary

This synchronize event was a merge-from-main commit (3ca0309) — no content changes to docs/MIGRATION-PLAYBOOK.md beyond what was already reviewed and approved in the previous passes.

The content is unchanged and clean:

Monitors (lines 506–516) — REJECT logic is sound. when: "on-skill-invoke:<skill-name>" now verbatim-matches the upstream Optional fields table and is attributed as "the documented … monitor field." The prior finding is fully resolved.

bin/ (lines 517–525) — REJECT scope correctly bounded to marketplace-wide adoption, not bin/ as a directory concept. Name-collision risk articulation is accurate; deferral to #1373 is correct.

subagentStatusLine (lines 526–532) — REJECT for cosmetic-only value is correctly applied. Dual upstream citation is appropriate.

Section shape matches the existing "Deferred surfaces — decision record" style exactly: date-stamped header, enforcement-hierarchy preamble, bold verdicts, actionable revisit triggers, upstream-cite-only (no schema recap).

No new findings. Ready to merge.

[cursor]

Risk: low. Not approving because Cursor Bugbot skipped (usage limit reached) and did not complete automated review. Human review is needed before merge; no reviewers were assigned because no non-author human maintainers are available on this repository.

  

_{Sent by Cursor Approval Agent: Pull Request Router and Approver}