fix: correct plugin-system inaccuracies and harden references#2
Merged
Conversation
Audited every file against current official Claude Code docs (verified this session) and fixed the inaccuracies found: - marketplace.json: drop off-schema `owner.url` (the documented owner object supports only `name` + `email`) and use the documented contact field with a role-based shared inbox; add the `$schema` pointer to the published SchemaStore marketplace schema for editor validation. - MIGRATION-PLAYBOOK.md: components are namespaced by the plugin's own `name`, not the marketplace name (`/<plugin-name>:foo`); correct the prior `/melodic-software:foo` claim. Tighten userConfig detail: supported types include directory/file, and non-sensitive values are stored under `pluginConfigs[<id>].options`. - CLAUDE.md: make the canonical-docs table comprehensive (plugin dependencies, slash commands, memory, the .claude directory, tools reference) and cite the SchemaStore JSON Schemas for the repo's JSON. Sources: plugins-reference, plugin-marketplaces, sub-agents, memory docs at code.claude.com; schemas at json.schemastore.org. `claude plugin validate .` passes (only the expected "no plugins defined" warning). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jun 28, 2026
This was referenced Jul 4, 2026
Merged
This was referenced Jul 11, 2026
feat: add review-toolkit plugin (6 reviewer agents + quality-gate and code-review-fanout skills)
#71
Merged
This was referenced Jul 12, 2026
kyle-sexton
added a commit
that referenced
this pull request
Jul 12, 2026
Address two more Codex P2 findings plus the analogous coaching case: - codebase-detection case (#2): the eval repo has no real auth-flow module, so grounding would fail or reward inventing sources. Reframe to the routing + graceful-degradation invariant — resolve to codebase mode, discover from live files, and ask the user to point when no grounding exists rather than inventing repo sources. - primary-source case (#5) and coaching case (#4): a fresh topic invocation runs the mission interview before teaching, so expecting immediate content rewarded skipping the mission gate. Make both gate-aware — respect the new-workspace mission flow while asserting the grounding / one-question-coaching invariants.
This was referenced Jul 12, 2026
kyle-sexton
added a commit
that referenced
this pull request
Jul 13, 2026
… hardening (#138) Applies the resolved `planning/setup` hardening to `knowledge/setup`'s `library_dir` seam (same single-directory `userConfig` shape, same latent issues). ## Changes **`plugins/knowledge/skills/setup/SKILL.md`** - **Precedence** — step 1 now resolves the full documented order (Managed > `--settings` > Local > Project > User), warns when higher layers are unreadable instead of declaring a lower value authoritative, and surfaces layer shadowing before the project write. - **Portability** — step 5 guards the tracked project write: never propagate a machine-specific personal-layer value into team settings; route personal-only overrides to `.claude/settings.local.json` (portability required only for the shared project write). - **Declared-convention alignment** — inspect the repo's declared working-notes/artifacts convention even when a value is set; surface divergence and offer to reconcile. **`plugins/codebase-audit/skills/setup/SKILL.md`** (partial match — writes a tracked `.md`, not settings) - Applied only the precedence/shadowing subset: step 1 reports the *effective additively-merged* config across user-global → team → local layers (and warns on unreadable layers), instead of summarizing the team file alone. Settings-write portability specifics do not apply. ## Deviations (own-flagged) 1. **Fix #3 premise softened for knowledge.** The issue's fix #3 parenthetical assumed knowledge "honors that convention over the config at write time" (true for planning). Verified via `skills/youtube/extraction/lib/work-root.js` and the youtube pipeline that **knowledge resolves `library_dir` directly at write time — no skill overrides it with a repo convention at runtime.** Documenting that behavior would be false, so I softened the imported write-time-override claim: `library_dir` is runtime-authoritative, and setup's job is to keep it *aligned* with any declared convention. Fixes #1 and #2 are unaffected. 2. **`codebase-audit` version bump not in issue scope.** Patch-bumped `0.1.0 → 0.1.1` because its SKILL behavior changed; the issue only specified the `knowledge` minor bump. ## Verification - `knowledge` `plugin.json` minor bump `0.2.0 → 0.3.0`; `codebase-audit` `0.1.0 → 0.1.1`. - `claude plugin validate` clean on both plugins. - markdownlint clean on both edited files. Refs melodic-software/medley#1463 <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Changes are limited to plugin skill documentation and version metadata; no application runtime or security-sensitive code paths are modified. > > **Overview** > **Hardens setup skills** for the `knowledge` and `codebase-audit` plugins so interactive setup reflects layered config reality instead of treating a single team file as authoritative. > > For **`knowledge/setup`**, step 1 now follows the full Claude Code precedence chain (Managed → `--settings` → Local → Project → User), warns when higher layers are unreadable, and calls out when a project write would stay shadowed. A new step reconciles `library_dir` with repo-declared working-notes conventions even when a value is already set. Persistence (step 5) blocks copying machine-specific personal paths into tracked project settings, routes personal-only overrides to `.claude/settings.local.json`, and the output section documents honest pipeline behavior (`book-distill` ignores `library_dir`; YouTube does not yet honor it). **`knowledge`** bumps **0.2.0 → 0.3.0**. > > For **`codebase-audit/setup`**, step 1 is expanded to summarize the **effective merged** config across user-global → team → local layers (including dimension opt-outs via empty source lists), explain that only the team file is written, and warn when overlays block re-enabling dimensions. **`codebase-audit`** patch-bumps **0.1.0 → 0.1.1**. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit f13139a. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY -->
kyle-sexton
added a commit
that referenced
this pull request
Jul 15, 2026
## Summary Executes the owner-approved tier-2 restores from the salvage sweep (items #2–#12 plus semantic-drift items D1–D4): pre-migration behavior and guidance dropped at the cutover, restored and genericized to the marketplace's repo-agnostic seams. Every touched plugin gets a version bump and CHANGELOG entry. | Plugin | Version | Restored | |---|---|---| | claude-config-audit | 0.4.0 | Pre-computed context blocks (3 skills) + `allowed-tools` scoping; all script paths `${CLAUDE_PLUGIN_ROOT}`-rooted; every `!` command empirically tested with fallbacks | | event-storming | 0.3.0 | `--design-level` missing-prerequisite guard (never fabricate a process model) + eval id 7; bare "memory" refs swept to the `${CLAUDE_PLUGIN_DATA}/history.jsonl` seam | | planning | 0.9.0 | Agent-team vs fan-out composition guidance in /architect Step 4.5 (decompose by context boundary, never lifecycle role; disjoint file ownership); baseline capture routes to `/implementation:verify-improvement` SSOT when installed; devils-advocate regains the `/implementation:verify-changes` pointer | | session-flow | 0.4.0 | Retro ecosystem-improvement catalog (`reference/`, 221 lines) — hook-event table reconciled against the current hooks doc (8 events added, 2 medley errors fixed); handoff failure-pattern `context/gotchas.md` | | review-toolkit | 0.5.0 | Normalization-pipeline model assignment (Stage 0/3 Sonnet, 1–2 deterministic/Haiku, 4 deterministic) + per-stage heading annotations | | implementation | 0.5.0 | Optional `tool-pin` version-drift warning in /lint + ecosystem-commands contract 1.1.0 (additive schema key, per the contract's own versioning rule); /implement over-correction trap logs to the session retro when installed | | codebase-audit | 0.2.0 | Background/unattended Phase 1 fan-out variant (graceful-degrade framing) | | code-tidying | 0.4.0 | Stdlib-only frontmatter-fence integrity check in the self-update lane (pass/fail paths tested) | | prototype | 0.2.1 | Composition table (fully-qualified marketplace names, `when installed` gating); named `session-flow:handoff` seam in the auto-invoke gate | ## Playbook compliance - Repo-agnostic: coupling grep over all added lines is clean (no medley paths, no consumer-repo names, no reach-outs); cross-plugin references use fully-qualified names with graceful "when installed" degrade. - Fresh-docs: `disable-model-invocation`/frontmatter, `${CLAUDE_PLUGIN_ROOT}` substitution scope ("Skill and agent content — anywhere the placeholder appears"), and the hook-event table were verified against code.claude.com docs this session. - `docs/conventions/ecosystem-commands/` confirmed repo-owned (not a standards-managed materialization) before the schema edit. - All nine plugins pass `claude plugin validate`; catalog passes `claude plugin validate --strict`; new/changed markdown passes markdownlint-cli2 (0 errors); the new eval validates against `evals.schema.json`. ## Security review note (claude-config-audit 0.4.0) The pre-computed context blocks add a code-execution-at-skill-load surface: `!` commands run when the skill is invoked. Scope check per the plugin-acceptance review: all commands invoke scripts **bundled inside the plugin** via `${CLAUDE_PLUGIN_ROOT}` (no `../` reach-outs, no absolute paths), are read-only inventory/count operations, carry `|| echo`-style fallbacks so load never hard-fails, and make no network calls. The `allowed-tools` entry pre-approves exactly the one bundled read-only script, nothing broader. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_011xHkkNc7CR98L8Xz9Mu7ZA --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
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 was referenced Jul 21, 2026
This was referenced Jul 22, 2026
Open
5 tasks
This was referenced Jul 22, 2026
This was referenced Jul 22, 2026
kyle-sexton
added a commit
that referenced
this pull request
Jul 22, 2026
Resolve version-collision conflicts with changes that landed on main (#922/#817): - work-items/.claude-plugin/plugin.json: restack version 0.21.1 -> 0.21.3, strictly above main's landed 0.21.2 (avoids a silent version match). - work-items/CHANGELOG.md: preserve main's [0.21.2] and [0.21.1] entries; #818's own entry relabeled to [0.21.3], newest on top. - work-items/skills/triage/SKILL.md: attention-view bucket #2 kept as the dual-axis "Raw marker" wording (both sides made the identical change).
This was referenced Jul 22, 2026
fix(disk-hygiene): reason about volume-root rejection instead of blanket-denying non-OS drives
#1063
Merged
kyle-sexton
added a commit
that referenced
this pull request
Jul 23, 2026
…ld (PR #1162 review) Two Important review findings on the scan-briefing change: - scan-briefing.md intro declared "four parts" but the template has five sections; the omitted one is §4 badge-acceptance heuristics — exactly the scan-time calibration this change exists to inject (F4). A caller following the stated count could send a briefing without it. Now "five parts", heuristics enumerated. (claude review #1 + Codex P2) - Phase 1.5 gated on candidates that "will carry a Strong badge" and their shallow-signal, but at Phase 1.5 only the scan-time confidence field exists (strong|worth-exploring|speculative) — the recommendation badge is assigned in Phase 2. Gate now keys on `confidence: strong`, and Phase 2 states the confidence->badge mapping explicitly, resolving the field-name and case-style mismatch. (claude review #2) Also sharpened the durable artifact's deepening vs shallow-signal field descriptions with contrasting examples so they aren't filled redundantly (claude review nit). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
kyle-sexton
added a commit
that referenced
this pull request
Jul 23, 2026
Codex P2: the new step-3 dedup had no eval guard — the full-batch fixture described collect-then-correct with no dedup, so a regression removing it (and the reporter->remedy preservation it enables) would still pass the model-graded check. Adds eval #6 exercising a shared-root-cause session (multiple correctors flag one from-memory claim) and asserting the merge, per-reporter remedy keying + per-rank application, and single attributed report; strengthens eval #2's full-batch expectations to include the dedup step and the remedy-carrying ledger. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This was referenced Jul 23, 2026
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
Full per-file audit of the repo against current official Claude Code docs (re-verified this session per the repo''s fresh-docs mandate). The vast majority of existing content was confirmed accurate; this PR fixes the real inaccuracies found and strengthens references. No code, only manifest/docs.
Real defects fixed
marketplace.json— off-schemaowner.url. The documentedownerobject supports onlyname(required) +email(optional) —urlis not a valid owner field. Replaced with the documented contact field using theinfo@melodicsoftware.comshared inbox (matches the docs''DevTools Team/devtools@example.comteam-alias example; no personal PII). Source: plugin-marketplaces "Owner fields".MIGRATION-PLAYBOOK.md— wrong namespacing. Components are namespaced by the plugin''s ownname, not the marketplace name. Corrected/melodic-software:foo→/<plugin-name>:foo. Source: plugins-reference (plugin-dev:agent-creatorexample).Polish / accuracy
marketplace.json— added$schema→ published SchemaStore marketplace schema (editor validation; Claude Code ignores it at load time).MIGRATION-PLAYBOOK.md—userConfigtypes also includedirectory/file; non-sensitive values stored underpluginConfigs[<id>].options.CLAUDE.md— canonical-docs table made comprehensive (plugin dependencies, slash commands, memory,.claudedirectory, tools reference) + cited the two SchemaStore JSON Schemas.Verified-correct (no change needed)
All plugin env vars/paths (
CLAUDE_PLUGIN_ROOT/DATA/PROJECT_DIR, cache/data paths),userConfig→keychain storage,hooks/hooks.json, agent shadowing precedence,extraKnownMarketplaces+CLAUDE_CODE_PLUGIN_SEED_DIRheadless guidance,claude plugin validate/--plugin-dir, all README commands, and.gitignore(CLAUDE.local.mdand.claude/rules/are both current, documented features).Validation
claude plugin validate .→ passes (exit 0; only the expected "no plugins defined" warning). JSON parses.🤖 Generated with Claude Code