refactor(marketplace): reorganize plugin taxonomy and naming - #204
Merged
Conversation
## Summary Reorganize the marketplace under a `domain-noun:action-verb` naming grammar and a 15-category taxonomy. Renames, splits, and merges take the catalog from 43 to 45 plugins with zero consumer loss: every old name is preserved in an append-only `renames` map, so installed plugins migrate automatically at session start (settings-key rewrite; remote sources report a cache miss and reinstall once). ## Naming and structure - Grammar: `domain-noun:action-verb`, no stutter, no root-echo; base-first family layout. The full doctrine (grammar, no-stutter+root-echo, base-first family, vendor-CLI verb, shadow history, buckets-are-metadata, discovery-intent split, incumbency rule) lives in the migration playbook. - Category vocabulary: single owner doc `docs/CATALOG-TAXONOMY.md` (15 categories + glosses, noun-form rule, lifecycle-primary/subject principle, singleton governance, category-level triggers, generation contract). marketplace.json conforms; consumers cite, never restate. ## Version propagation Same-name content changes propagate through `/plugin update` only when the `version` field increases, so the 6 changed same-name plugins are bumped (prototype, knowledge, firecrawl, code-tidying, source-control, planning), with 5 Keep-a-Changelog entries (firecrawl is bump-only). Renames, splits, and merges are version-independent — they migrate via the renames map — so their targets carry no version-exceed gate. ## Catalog generation New `scripts/generate-catalog.mjs` renders the README catalog from marketplace.json (category) and plugin.json (description) between markers; `scripts/validate-plugins.sh` runs it with `--check` so catalog drift fails CI. It keys on description, not version, so version bumps never touch it. ## Docs Both audit snapshots (evals-coverage, extensibility-contract-grading) are reconciled to post-reorg names via a two-layer temporal split: a fresh 2026-07-15 live-scan layer over the current 45-plugin tree, and a frozen 2026-07-12 program-record layer keeping the identities each medley issue was filed against. Eval presence was re-verified (92/102 skills covered); no warrant or contract grade was re-audited. The interview decision record (D1-D24) is persisted at `docs/topics/plugin-organization/PLAN.md`. ## Verification - `scripts/validate-plugins.sh`: pass (all manifests + strict catalog sync) - `scripts/run-plugin-tests.sh`: 7 passed, 0 failed - markdownlint-cli2: 0 errors on all touched markdown - renames map: 11 entries, append-only, no cycles; rename-integrity grep clean (no stale old-namespace invocations in active content) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0163dXPBdRYFpx4wTtS648tE
The taxonomy reorg's renames were staged on Windows, where git cannot represent the executable bit, so 26 shebang scripts in renamed or new plugin dirs (plus the new scripts/generate-catalog.mjs) entered the index as 100644. The hygiene exec-bit check requires any shebang file to be 100755. Restore the bit via git update-index --chmod=+x. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0163dXPBdRYFpx4wTtS648tE
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b72139991b
ℹ️ 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".
… splits The renames map only migrates a 1:1 plugin rename, not a skill split into a new plugin, so users on the pre-split `implementation` bundle or on the `claude-config-audit` -> `claude-config` rename get no automatic signal that build/test/lint/verify or memory-health moved. Add a "Migrating from" section to each README (matching the existing knowledge/machine-health convention) with the exact install commands to restore the moved skills.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 3fcf2cda37
ℹ️ 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".
…ill renames scripts/validate-plugin-contracts.mjs still pointed at skills/ai-briefing after that skill directory was renamed to skills/generate, so the active-profile, AI_BRIEFING_PROFILE, remote-asset, and brand-overlay checks were silently skipped. Retarget all four lookups to skills/generate; validate-plugin-contracts.mjs now executes and passes those checks against the code users actually receive. Document every same-plugin, skill-only rename introduced by the taxonomy reorg in each plugin's CHANGELOG.md (old command -> new command), so an existing install of an unchanged plugin has a paper trail for why its old slash command stopped resolving: tdd, ai-briefing, bug-report, claude-ops (three skills), context7, docs-hygiene, machine-health, skill-quality. This is a documented breaking change, not a compatibility shim -- no old command is restored.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b1b49a8388
ℹ️ 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".
Comment on lines
+64
to
+66
| 1. `~/.claude/codebase-health.md` (user-global, optional) | ||
| 2. `.claude/codebase-health.md` (team, tracked) | ||
| 3. `.claude/codebase-health.local.md` (personal overlay, gitignored) |
There was a problem hiding this comment.
When an existing repo is migrated by the marketplace rename from codebase-audit to codebase-health, its tracked audit configuration remains at .claude/codebase-audit.md, but the new audit only looks for the codebase-health filenames here. The first /codebase-health:audit after update will treat the config as absent and infer/generic-default the dimensions, silently ignoring any custom sources or opt-outs until a user manually renames the file; add a legacy read/migration path in the audit/setup flow before dropping the old convention.
Useful? React with 👍 / 👎.
4 tasks
kyle-sexton
added a commit
that referenced
this pull request
Jul 15, 2026
…angelog/readme) Combines this branch's 0.4.0 setup-skill version/description with main's 0.3.1 taxonomy-sync changelog entry (#204): version stays 0.4.0 (already exceeds 0.3.1), both changelog entries stack in descending order per Keep a Changelog, and the generated README catalog line is regenerated to match the merged plugin.json description.
kyle-sexton
added a commit
that referenced
this pull request
Jul 16, 2026
… follow-ups) (#205) ## Summary The three follow-ups deliberately deferred out of #204 (recorded in its PR body), each decision-gated with the maintainer before editing. Net **−341 lines**; no plugin manifest, schema, or skill behavior touched. ## #1 — Retire the audit snapshots Delete `docs/evals-coverage.md` and `docs/extensibility-contract-grading.md`. They were hand-stamped, point-in-time records that drift the moment a plugin changes (the reorg already forced a two-layer temporal re-stamp). **Retire over generate.** The durable policy already lives in `docs/MIGRATION-PLAYBOOK.md` — the warrant rule + consumer-verify recipe ("Evals — warrant policy and consumer-verify recipe") and the four-seams contract ("Extensibility contract v2.1"). A generator could derive only eval *presence* (a live glob) — the minority of one doc and none of the other; class, contract grades, and medley program state stay irreducibly hand-graded or externally-owned. Generating only the presence slice yields a half-generated hybrid that still drifts on its biggest surface. Retire is the clean fit. **Gaps captured first.** Two warranted-but-unowned eval gaps were recorded *only* in the retired snapshot (verified still live against the tree): `context7/setup` and `planning/wayfind`. Filed durably before deletion: - `melodic-software/medley#1537` — evals(context7/setup) - `melodic-software/medley#1538` — evals(planning/wayfind) Inbound pointers updated: README doc-index (2 bullets removed) and the playbook's evals section (now states on-demand verification instead of pointing at a deleted snapshot). No dangling references remain (repo-wide grep clean). ## #2 — Reclassify the depth-variant convention tension The playbook stated a depth/intensity variant "takes an argument, never a sibling," yet `discovery`'s `explore-deep` / `research-deep` ship as sibling skills. Inspection shows they are **structural, not depth**: - `explore-deep` — `context: fork` + `agent: general-purpose`: a distinct execution *topology* (isolated forked subagent), declared in frontmatter, not expressible as a runtime argument. - `research-deep` — a dispatcher to the heaviest isolated tier (workflow engine, forked subagent, or inline fallback), with its own body and auto-invocation description. The convention needed no exception — it needed a sharper structural/depth test. Amended to classify **execution tier as a structural axis** (sibling) and bind the `-deep` suffix to that axis, so the naming no longer reads as a violation and a future reader does not re-flag it. A true effort knob on one execution path still takes an argument. No skills renamed. ## #3 — README revisit-condition dedup Assessed, closed **no-op**. The coupling flagged in #204 is a documented, directional SSOT+index: `docs/CATALOG-TAXONOMY.md` (L71–73) declares plugin-scoped revisit conditions are *owned by each plugin's README* and the taxonomy "Trigger register" lists them "only as pointers." The READMEs are the single owners of genuine plugin-specific rationale; the register summarizes them. Nothing to dedup. Confirmed none of the three sections cross-names the taxonomy doc. ## Verification - `scripts/validate-plugins.sh`: pass (all manifests + strict catalog sync) - `scripts/run-plugin-tests.sh`: 7 passed, 0 failed - `markdownlint-cli2`: 0 errors on both touched markdown files - Repo-wide grep for the retired doc names: no remaining references ## Note (not in this PR) `docs/hook-migration-audit.md` is the same "point-in-time audit" genus as the two retired here. Left untouched; flagged for a consistency decision in a later pass. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_0163dXPBdRYFpx4wTtS648tE Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reorganize the marketplace under a
domain-noun:action-verbnaming grammar and a 15-category taxonomy. Renames, splits, and merges take the catalog from 43 to 45 plugins with zero consumer loss: every old name is preserved in an append-onlyrenamesmap, so installed plugins migrate automatically at session start (settings-key rewrite; remote sources report a cache miss and reinstall once).Naming and structure
domain-noun:action-verb, no stutter, no root-echo; base-first family layout. The full doctrine (grammar, no-stutter+root-echo, base-first family, vendor-CLI verb, shadow history, buckets-are-metadata, discovery-intent split, incumbency rule) lives in the migration playbook.docs/CATALOG-TAXONOMY.md(15 categories + glosses, noun-form rule, lifecycle-primary/subject principle, singleton governance, category-level triggers, generation contract).marketplace.jsonconforms; consumers cite, never restate.Version propagation
Same-name content changes propagate through
/plugin updateonly when theversionfield increases, so the 6 changed same-name plugins are bumped (prototype,knowledge,firecrawl,code-tidying,source-control,planning), with 5 Keep-a-Changelog entries (firecrawlis bump-only). Renames, splits, and merges are version-independent — they migrate via the renames map — so their targets carry no version-exceed gate.Catalog generation
New
scripts/generate-catalog.mjsrenders the README catalog frommarketplace.json(category) andplugin.json(description) between markers;scripts/validate-plugins.shruns it with--checkso catalog drift fails CI. It keys on description, not version, so version bumps never touch it.Docs
Both audit snapshots (
evals-coverage,extensibility-contract-grading) are reconciled to post-reorg names via a two-layer temporal split: a fresh 2026-07-15 live-scan layer over the current 45-plugin tree, and a frozen 2026-07-12 program-record layer keeping the identities each medley issue was filed against. Eval presence was re-verified (92/102 skills covered); no warrant or contract grade was re-audited. The interview decision record (D1–D24) is persisted atdocs/topics/plugin-organization/PLAN.md.Verification
scripts/validate-plugins.sh: pass (all manifests + strict catalog sync)scripts/run-plugin-tests.sh: 7 passed, 0 failedmarkdownlint-cli2: 0 errors on all touched markdownFollow-ups (not in this PR — flagged for a decision, not deferred plan work)
evals-coverage,extensibility-contract-grading) are hand-stamped and drift-prone; candidate for generate-or-retire (derive coverage from a live glob, keep only durable policy prose).explore/explore-deepandresearch/research-deepship as sibling skills.🤖 Generated with Claude Code
https://claude.ai/code/session_0163dXPBdRYFpx4wTtS648tE