Plugin: discovery · Categories: missing externalization (2), non-resolving path (4)
Source: work-readiness sweep (read-only audit vs docs/PLUGIN-PHILOSOPHY.md + docs/MIGRATION-PLAYBOOK.md)
Findings
plugins/discovery/skills/setup/SKILL.md:47 and :63 — "enabled (see docs/adr/0001-defer-gitbook-as-knowledge-vault-backend.md) — deferred and non-writable"plugins/discovery/CHANGELOG.md:32 — same reference (historical, lower concern)
Why it breaks agnosticism
docs/adr/0001-...md is a marketplace-repo file — not bundled in the plugin, not in the consumer repo. Once installed to the cache-isolated plugin directory it resolves to nothing; a consumer reading the deferred-backend rationale in the setup skill hits a dead path. Violates PLUGIN-PHILOSOPHY cache-isolation ("reference only files inside the plugin via ${CLAUDE_PLUGIN_ROOT}"), migration-gate step 4 (de-couple from source repo), and root CLAUDE.md "never cross-reference files/file names".
Fix direction
Inline the one-sentence rationale (gitbook backend is deferred and non-writable; durable writes target docs) into the setup skill, or bundle the decision as ${CLAUDE_PLUGIN_ROOT}/reference/… and cite that. Never point installed skill text at publisher-repo internals by bare path.
Plugin:
discovery· Categories: missing externalization (2), non-resolving path (4)Source: work-readiness sweep (read-only audit vs docs/PLUGIN-PHILOSOPHY.md + docs/MIGRATION-PLAYBOOK.md)
Findings
plugins/discovery/skills/setup/SKILL.md:47and:63— "enabled (seedocs/adr/0001-defer-gitbook-as-knowledge-vault-backend.md) — deferred and non-writable"plugins/discovery/CHANGELOG.md:32— same reference (historical, lower concern)Why it breaks agnosticism
docs/adr/0001-...mdis a marketplace-repo file — not bundled in the plugin, not in the consumer repo. Once installed to the cache-isolated plugin directory it resolves to nothing; a consumer reading the deferred-backend rationale in the setup skill hits a dead path. Violates PLUGIN-PHILOSOPHY cache-isolation ("reference only files inside the plugin via${CLAUDE_PLUGIN_ROOT}"), migration-gate step 4 (de-couple from source repo), and root CLAUDE.md "never cross-reference files/file names".Fix direction
Inline the one-sentence rationale (gitbook backend is deferred and non-writable; durable writes target
docs) into the setup skill, or bundle the decision as${CLAUDE_PLUGIN_ROOT}/reference/…and cite that. Never point installed skill text at publisher-repo internals by bare path.