From e1e1680856b26f4335abe6b2491f007ee2b96119 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Wed, 15 Jul 2026 18:36:37 -0400 Subject: [PATCH] docs: retire audit snapshots, reclassify depth-variant convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Post-#204 reorg follow-ups. Retire audit snapshots (#1). Delete docs/evals-coverage.md and docs/extensibility-contract-grading.md — point-in-time records whose durable policy already lives in the migration playbook (warrant rule + consumer-verify recipe; four-seams contract). Generating would derive only eval presence (a glob) while class, contract grades, and medley program state stay hand-stamped, so retire beats a half-generated hybrid. The two warranted-but-unowned gaps recorded only in the snapshot are captured first in melodic-software/medley#1537 (context7/setup) and #1538 (planning/wayfind). Inbound pointers in README and the playbook are updated. Reclassify depth-variant convention (#2). The playbook said a depth/intensity variant takes an argument, but discovery's explore-deep/research-deep ship as siblings. They are structural, not depth: explore-deep is a `context: fork` execution topology and research-deep a heavier dispatch tier, both fixed in frontmatter and not expressible as a runtime argument. Amend the convention to classify execution tier as a structural axis and bind the `-deep` suffix to it. README revisit-condition dedup (#3) assessed and closed no-op: the coupling is a documented, directional SSOT+index (CATALOG-TAXONOMY.md owns only pointers; each README owns its condition). Verification: scripts/validate-plugins.sh pass; scripts/run-plugin-tests.sh 7 passed, 0 failed; markdownlint-cli2 0 errors on touched markdown. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_0163dXPBdRYFpx4wTtS648tE --- README.md | 2 - docs/MIGRATION-PLAYBOOK.md | 14 +- docs/evals-coverage.md | 147 ------------------- docs/extensibility-contract-grading.md | 188 ------------------------- 4 files changed, 10 insertions(+), 341 deletions(-) delete mode 100644 docs/evals-coverage.md delete mode 100644 docs/extensibility-contract-grading.md diff --git a/README.md b/README.md index 2830b7cfd..5b24e0532 100644 --- a/README.md +++ b/README.md @@ -120,9 +120,7 @@ Install one: `/plugin install @melodic-software`. - `plugins/` — one directory per plugin. - `docs/MIGRATION-PLAYBOOK.md` — design charter, extensibility model, the per-plugin migration gate, and the local development loop. - `docs/extensibility-contract-smoke-tests.md` — verified behavior for gaps the official docs leave open. -- `docs/extensibility-contract-grading.md` — point-in-time grade of every shipped plugin against the contract. - `docs/hook-migration-audit.md` — point-in-time audit of medley's general-purpose hooks for extraction into `guardrails`/`claude-ops`. -- `docs/evals-coverage.md` — point-in-time skill-eval coverage snapshot: which skills warrant evals, which are owed backfill, and the explicit skips. - `docs/ai-briefing-design.md` — engine/profile/personal split design record for the `ai-briefing` migration (reference adopter of the profiled-folder convention). - `docs/CI-RUNNER-ROUTING.md` — local-runner selection, hosted boundaries, and failure recovery. - `CLAUDE.md` — operating rules for AI agents working in this repo (fresh-docs mandate + canonical links). diff --git a/docs/MIGRATION-PLAYBOOK.md b/docs/MIGRATION-PLAYBOOK.md index cf95686be..fdab90e0d 100644 --- a/docs/MIGRATION-PLAYBOOK.md +++ b/docs/MIGRATION-PLAYBOOK.md @@ -88,7 +88,13 @@ Applying that precedence, the grammar of an invocation is `/:` first (`design`, `design-handoff`, `implement`, `implement-dispatch`) so prefix typeahead and sorted listings group the family. A standalone skill keeps natural English order (`batch-simplify`, `quality-gate`). A structural variant earns a new sibling name; a depth/intensity variant takes an argument, never - a sibling. + a sibling. **Execution tier counts as structural:** a variant that changes execution *topology* — an + isolated forked subagent (`context: fork`) or a heavier dispatch tier (workflow engine, forked + subagent, or inline fallback) — is fixed in frontmatter and cannot be a runtime argument, so it earns + a sibling. `discovery`'s `explore-deep` (a `context: fork` variant of `explore`) and `research-deep` + (a dispatch variant of `research`) are siblings on this axis; the `-deep` suffix names that isolation + tier, not a depth knob on the same execution path — a true effort knob on one execution path still + takes an argument. - **A vendor-CLI plugin names its skills after the vendor's own CLI verbs.** A tool-scoped plugin wrapping a CLI mirrors that CLI's verb vocabulary — `/playwright:test` mirrors `npx playwright test`; a firecrawl decomposition would use `scrape` / `crawl` / `map` per @@ -246,9 +252,9 @@ from a knowledge corpus with no decision contract — `playbooks:fable-5`, `tdd` `codebase-health/setup` eval is the model). Gray-zone skills (thin mechanical wrappers, reference-ish routers) are **author-confirm**: re-check the warrant against the live `SKILL.md` at authoring time and record an explicit skip verdict if it dissolves — a satisfied "looks covered" is not a warrant. -Coverage against this rule is snapshotted per audit in -[`evals-coverage.md`](evals-coverage.md); that doc is the point-in-time record, this section is the -policy. +This section is the policy; current coverage is verified on demand — a live glob of +`plugins/*/skills/*/evals/evals.json` against the tree, read against the warrant rule above — never a +checked-in snapshot that decays the moment a skill lands. **Rich form.** Each case carries `id`, a kebab-case `name`, a `prompt`, an `expected_output` description, optional `files` fixtures, and an `expectations` array of objectively-verifiable checks diff --git a/docs/evals-coverage.md b/docs/evals-coverage.md deleted file mode 100644 index 4ab3a8a5d..000000000 --- a/docs/evals-coverage.md +++ /dev/null @@ -1,147 +0,0 @@ -# Skill-eval coverage — warrant snapshot - -Point-in-time record of which shipped skills carry model-graded evals, which *warrant* them and are -owed backfill, and which are explicit **skips**. This is an **audit snapshot**, not durable policy — -the warrant rule and the consumer-verify recipe are policy and live in the -[migration playbook](MIGRATION-PLAYBOOK.md) ("Evals — warrant policy and consumer-verify recipe"). -This table records where each plugin stood on the stamp date and which backfill issue owns each gap. -Empirical claims decay: a row is only true as of the stamp below. - -> **Reconciliation — 2026-07-15 (taxonomy reorg).** The plugin-taxonomy reorg renamed, split, and -> merged plugins (43 → 45), so this document carries two layers, kept apart by a single temporal line: -> -> - **Current-state layer — re-scanned 2026-07-15, authoritative.** The *Current coverage* section -> below, plus the *Deferred* and *Skip* classifications, were re-derived from a fresh glob of -> `plugins/*/skills/*/evals/evals.json` across the live 45-plugin tree and use post-reorg names. -> - **Program-record layer — frozen at 2026-07-12.** The *Backfill program* batch table and the -> *Future coverage* section are the dated record of the `melodic-software/medley` wave-2 backfill -> program. They keep the pre-reorg plugin/skill identities the medley issues were filed against and -> are **not** name-swept — the renames map in `.claude-plugin/marketplace.json` and the split -> changelogs (`implementation` 0.6.0, `work-items` 0.7.0, `claude-config` 0.5.0) are the -> authoritative old→new mapping. -> -> Only eval *presence* was re-verified this session; no skill's warrant classification was re-graded. - -Stamped 2026-07-12, built from the per-skill eval presence read that session against the 42 plugins -then in `.claude-plugin/marketplace.json` and the class column of -[`extensibility-contract-grading.md`](extensibility-contract-grading.md) (retrofit-audit -`melodic-software/medley#1388`, which graded 41 — the `miro` MCP-server plugin landed after that audit -and is classified below). Presence was read per-skill from each `plugins/

/skills//evals/evals.json`; -because sibling workers backfill concurrently, that read is accurate only at its instant — the batch -table's Status column carries the reconciliation and the live tree is the source of truth. -Emitter: evals-backfill `melodic-software/medley#1396`. - -## Current coverage (re-scanned 2026-07-15) - -Fresh glob across the live 45-plugin tree: **92 of 102 skills carry `evals/evals.json`.** The wave-2 -backfill program (batch table below) has essentially landed — every skill listed in those batches now -ships an eval. The 10 remaining uncovered skills fall into three buckets: - -- **Genuine gaps — warranted, unowned (2).** `context7/setup` and `planning/wayfind` (a skill that - postdates the wave-2 batches). Neither is owned by a listed batch (#1447 covered planning's seven - behavior skills, not `wayfind`; the setup self-scan #1462 did not list `context7`). Identified here; - **no backfill issue has been filed** — filing lands in `melodic-software/medley`, out of scope for - this repo. -- **Deferred (6).** `knowledge` (`book-distill`, `setup` — `youtube` and `course-digest` now ship - evals) and `songwriting` (`daily-practice`, `meter-prosody`, `setup`, `suno` — the other six skills - now ship evals). Both plugins are under open move-out gates; see *Deferred* below. -- **Skip — pure-reference (2).** `tdd/principles` and `playbooks/fable-5`; see *Skip* below. - -## Warrant rule (summary) - -Full rule + rationale: playbook "Evals — warrant policy and consumer-verify recipe". In brief a skill -**warrants** evals when it carries a judgment-bearing behavioral contract — triggering, routing, -refusal, or output shape that could silently regress. A skill is an explicit **skip** when it is -pure-reference (answers from a corpus, no decision contract) or a **hook** (deterministic, guarded by -`.test.sh`, no model-invoked skill). Gray-zone skills are marked **author-confirm**: the backfill -session re-checks the warrant against the live `SKILL.md` and records a skip verdict if it dissolves. - -## Backfill program — 2026-07-12 record (frozen) - -Frozen at the 2026-07-12 stamp with the pre-reorg identities each medley issue was filed against. -**Per the 2026-07-15 live scan every skill listed below is now covered**; the table is retained as the -dated program record, not a live to-do list. - -One issue per batch, each sized to one agent-session, sub-issue-linked under wave-2 map -`melodic-software/medley#1369`, `agent-ready`. Each batch issue carries the authoring recipe, the -schema path, and the per-skill warrant re-check instruction. The **Status** column is the -reconciliation as it stood at the 2026-07-12 stamp — `DONE` = all listed skills covered by concurrent -sibling backfill; `PARTIAL` = some remained; `OPEN` = none covered yet. - -| Batch issue | Skills | Status (at stamp) | -|---|---|---| -| `melodic-software/medley#1447` | planning: architect, brainstorm, design, design-handoff, devils-advocate, interview, prd (7) | **DONE** — all 7 backfilled concurrently | -| `melodic-software/medley#1448` | discovery: explore, explore-deep, research, research-deep, setup; claude-config-audit: memory-health (6) | **PARTIAL** — only `discovery/setup` remains; the other 5 backfilled concurrently | -| `melodic-software/medley#1449` | implementation: implement, implement-dispatch, build, lint, setup (5) | **OPEN** — #1420 (ecosystem-commands + setup) CLOSED → stable; build/lint/setup author-confirm | -| `melodic-software/medley#1450` | docs-hygiene: compress, declutter, encapsulation-audit, extract-ssot, rename-references (5) | **OPEN** | -| `melodic-software/medley#1451` | session-flow: handoff, orchestration-brief, retro, workflow; source-control: commit, pull-request, worktree (7) | **OPEN** | -| `melodic-software/medley#1452` | claude-ops: claude-code-changelog, claude-observability, claude-troubleshooting; prototype: logic, ui (5) | **DONE** — all 5 backfilled concurrently | -| `melodic-software/medley#1453` | context7, firecrawl, playwright, diagnose, teach, kindle-dedrm (6) | **DONE** — all 6 backfilled concurrently | -| `melodic-software/medley#1454` | event-storming: methodology, simulation; machine-health: machine-health, setup; skill-quality: skill-quality, setup (6) | **OPEN** — author vs current shipped behavior; owning retrofits update their eval on behavior change (simulation #1405, machine-health #1419, skill-quality #1418) | -| `melodic-software/medley#1455` | review-toolkit: quality-gate, code-review-fanout (2) | **OPEN** — #1421 CLOSED → stable; the six reviewer agents are not skills and carry no `evals/` slot | -| `melodic-software/medley#1458` | boris, thariq-skills (2) | **DONE** — both backfilled concurrently; reclassified from pure-reference for their `update`/`update --apply` routing + mutation-safety contract | -| `melodic-software/medley#1462` | setup-action skills self-scan: bug-report/setup, claude-ops/setup, work-items/setup, ai-briefing/setup, planning/setup + future landings (5) | **DONE** — all five backfilled; `ai-briefing/setup` and `planning/setup` caught by the scan as post-filing landings (uncovered, no family-batch owner — #1447 covers planning's seven behavior skills but not `setup`, #1457 covers ai-briefing behavior fixes not its eval — neither deferred) | - -## Deferred — author in the destination repo once separation lands - -Recorded as decisions, not silent omissions, each with a revisit trigger (playbook defer-record -pattern). Classifications reflect the 2026-07-15 scan; the move-out gates are preserved unchanged — -taxonomy placement did not resolve them. - -- **`songwriting`** — wave map `melodic-software/medley#1369` slates songwriting for a dedicated - personal repo, and its corpus/home is under an open decision gate (`melodic-software/medley#1402`, - needs-human). Six of its ten skills now ship evals (`co-write`, `diagnosis`, `object-writing`, - `rhyme`, `song-form`, `workflow`); four remain uncovered (`daily-practice`, `meter-prosody`, `setup`, - `suno`). Authoring the remainder in the marketplace now risks migrated/wasted work. **Revisit - trigger:** #1402 resolves songwriting's home → author the missing evals in whichever repo the plugin - lands (evals travel with the skill dir). -- **`knowledge`** — the knowledge artifacts move to a dedicated repo (`repo(knowledge-artifacts)` - `melodic-software/medley#1393`, needs-human) and the skill set is still growing (`course-digest` - landed pending `melodic-software/medley#1409`). `youtube` and `course-digest` now ship evals; - `book-distill` and `setup` remain uncovered. Both the home and the skill set are unsettled, so the - whole plugin is deferred regardless of which individual skills already carry evals. **Revisit - trigger:** #1393 fixes the plugin's home → author the missing evals in the destination repo. - -## Future coverage — setup-action skills (self-scanning batch) — 2026-07-12 record - -Frozen at the 2026-07-12 stamp (pre-reorg identities); retained as program record. The setup-action -retrofits (`melodic-software/medley#1428`–`#1432`, `#1435`) ship net-new `setup`/`configure` skills -over time, and several landed *without* evals. The ideal home for a new skill's eval is the retrofit PR -that ships it — `code-tidying` #1431 did exactly this (its `setup` shipped with an eval) — but when a -retrofit ships a setup skill uncovered, the gap falls to this program. To stop chasing each landing -individually, **`melodic-software/medley#1462` is a self-scanning catch-all**: it scans -`plugins/*/skills/setup/` for any setup skill lacking `evals/evals.json` and backfills those not -already owned by a plugin-family batch (`discovery/setup` #1448, `implementation/setup` #1449, -`machine-health`/`skill-quality` setup #1454) or deferred (`knowledge`, `songwriting`). A config-writer -skill is warrantable (the `codebase-audit/setup` eval is the model). Its first pass covered -`bug-report/setup`, `claude-ops/setup`, `work-items/setup`, `ai-briefing/setup`, and `planning/setup` -(the last two caught as post-filing landings — a scaffold/dep-install setup and a -`.claude/topic-docs.yaml` concern-file writer, each with no other eval owner). - -## Skip — pure-reference (2) - -Knowledge-only skills; the only argument is knowledge navigation or a query, with no mutation, refusal, -or external side-effect contract to guard. Explicit skip. (The `boris` and `thariq` skills in -`playbooks` were graded pure-reference too, but each additionally ships a mutating `update` action and -is therefore warranted — both now carry evals; see the frozen #1458 row.) - -| Plugin / skill | Verdict | -|---|---| -| playbooks/fable-5 | skip — pure-reference (`[full \| ]` is knowledge navigation, no mutation) | -| tdd/principles | skip — pure-reference (`[question or concept]` Q&A, no mutation) | - -## Skip — hook plugins (9) - -Silent-always-on components; no model-invoked skill (no `SKILL.md`). Contract tests are `.test.sh`, -not model-graded evals. Explicit skip. - -`actionlint`, `bash-lint`, `biome-format`, `eol-normalizer`, `markdown-formatter`, -`powershell-format`, `ruff-format`, `desktop-notification`, `guardrails`. - -## Skip — MCP-server plugins (1) - -`miro` bundles a stdio MCP server (`.mcp.json` + a TypeScript/Node package) whose behavior is guarded -by the plugin's own package tests (`vitest`), not model-graded evals — the server exposes no -`SKILL.md`, so there is no per-skill behavioral contract to grade. It additionally ships a `setup` -skill, which **does** carry an eval (present per the 2026-07-15 scan). Explicit skip for the server; -the setup skill is covered. diff --git a/docs/extensibility-contract-grading.md b/docs/extensibility-contract-grading.md deleted file mode 100644 index c1653cd8b..000000000 --- a/docs/extensibility-contract-grading.md +++ /dev/null @@ -1,188 +0,0 @@ -# Extensibility-contract grading - -Point-in-time grade of every shipped plugin against the extensibility contract v2.1 (the -["Extensibility contract v2.1 — the four seams"](MIGRATION-PLAYBOOK.md), convention-resolution -ladder, and setup-action sections of the [migration playbook](MIGRATION-PLAYBOOK.md)). This is an -**audit snapshot**, not durable policy — the playbook is the policy; this table records where each -plugin stood on the audit date and which follow-up issue owns each gap. Empirical claims decay: a -plugin's row is only true as of the stamp below. - -> **Reconciliation — 2026-07-15 (taxonomy reorg).** The reorg renamed, split, and merged plugins -> (41 graded → 45 shipped). This pass reconciles **names and membership only — no contract grade was -> re-audited this session** (only eval *presence* was re-verified, in -> [`evals-coverage.md`](evals-coverage.md)). Surviving plugins keep their 2026-07-12 grade under the -> post-reorg name; the renames map in `.claude-plugin/marketplace.json` and the split changelogs -> (`implementation` 0.6.0, `work-items` 0.7.0, `claude-config` 0.5.0) are the authoritative old→new -> mapping. Plugins with no 2026-07-12 grade — the reorg split-offs `toolchain`, `testing`, -> `verification`, `claude-memory`, plus the never-graded `ai-briefing` — are listed under *Pending -> contract re-grade* with their contract verdict explicitly unresolved. The `playbooks` merge -> (`boris` + `thariq-skills` + `fable-5-playbook`) also warrants a class re-grade — flagged in place. - -Graded 2026-07-12 against the 41 plugins in `.claude-plugin/marketplace.json` (retrofit-audit -`melodic-software/medley#1388`). Facts are Tier-0 — read from each plugin's `plugin.json`, skill -tree, and `hooks/hooks.json` this session; the MCP-carry column is the verdict from the MCP-servers -audit already codified in the playbook's ["MCP servers as a plugin component — carry -decision"](MIGRATION-PLAYBOOK.md) table (SHIP 0 / STAY 14 / DROP 0). - -## Grading dimensions - -- **Class** — `pure-reference` (knowledge-only skills, no config, no repo coupling), - `hook` (ships `hooks/hooks.json`, silent-always-on, controlled by matcher / kill-switch env), or - `behavior` (user- or model-invoked action skills). -- **Config seam** — which of the four seams the plugin exposes: `userConfig` (seam 1), - tracked rich config `.claude/.md|yaml|/**` (seam 2), consumer `CLAUDE.md`/rules only - (seam 3), or none needed. -- **Setup action** — the contract requires *every plugin carrying a `userConfig` or tracked-config - seam* to ship a re-runnable `setup`/`configure` action that interviews the consumer and writes the - tracked config. Present / missing / n/a (no config seam → not required). A **config seam** is a - file whose schema THIS plugin defines and the consumer authors to configure it (`userConfig`, - `.claude/.md`, `tidy-lanes/`, `songwriting/templates/`, `recurring-schedule.json`) — a - setup action scaffolds it. Reading the consumer's **pre-existing** conventions or tool configs via - seam 3 (`CLAUDE.md`, `REVIEW.md`, a markdownlint config, `worktree.baseRef`, - `UBIQUITOUS-LANGUAGE.md`) is **not** a setup-requiring seam — there is nothing plugin-specific to - write. -- **Ladder** — convention-resolution ladder compliance (config present → use; absent → infer & - persist / ask; else safe default; no baked repo assumptions). -- **Baked repo assumptions** — hardcoded consumer layout, `melodic-software/medley` paths, or other - source-repo coupling that survives into runtime behavior. -- **MCP-carry** — the plugin's MCP dependency and its carry verdict, per the playbook's audited - decision table. -- **Evals** — an `evals.json` / `evaluations.md` present in the plugin. - -## Verdict summary - -- **No net-new work: 34 of 41.** All 9 hook plugins, all 4 pure-reference plugins, and 21 behavior - plugins are contract-compliant as shipped (or their outstanding work is already owned by an - existing issue). -- **Net-new setup-action gap: 7** — `bug-report`, `claude-ops`, `code-tidying`, `discovery`, - `planning`, `songwriting`, `work-items` each expose a config seam but ship no (dedicated) - setup action. One retrofit issue filed per plugin (linked under wave-2 map - `melodic-software/medley#1369`). `songwriting` was reclassified from the issue's a-priori - pure-reference expectation to behavior once graded against the evidence (9 action skills + - a template-override seam); `work-items` carries an optional `.github/recurring-schedule.json` - tracked seam that its per-item scaffolding does not fully substitute for a re-runnable setup. -- **Baked repo assumptions: 0.** No plugin bakes a consumer layout into runtime behavior. Four - incidental `apps/`/`libs/`/`Platform.*` string hits are benign — test fixtures, eval-prompt - examples, generic top-level-dir enumerations, and Claude-Code-behavior documentation — not runtime - coupling. -- **Cross-cutting concerns owned elsewhere.** Eval coverage across all plugins is owned by the - evals-backfill emitter `melodic-software/medley#1396` — this audit records eval presence but emits - no eval issues. General-purpose in-repo hook migration into `guardrails`/`claude-ops` is owned by - `melodic-software/medley#1391`. Per-slug retrofits already filed: - `#1405` (event-storming), `#1408`/`#1409` (knowledge), `#1418` (skill-quality), `#1419` - (machine-health), `#1420` (implementation), `#1421` (review). Current Claude Code owns - `userConfig` prompting and persistence: knowledge, skill-quality, and machine-health setup skills - validate the rendered value or direct the user to `/plugin configure`; none edits `pluginConfigs`. - -**Membership reconciliation (2026-07-15, not a re-grade).** The reorg changed the plugin set, not the -frozen verdicts above: three pure-reference plugins (`boris`, `thariq-skills`, `fable-5-playbook`) -merged into `playbooks`; four behavior plugins were added by splits (`toolchain`, `testing`, -`verification` from `implementation`; `claude-memory` from `claude-config-audit`'s `memory-health`), -and `ai-briefing` surfaced as never graded — all five carry evals per the 2026-07-15 scan but no -contract grade (see *Pending contract re-grade*). Empirically, `setup` skills have since shipped for -most of the seven setup-action gaps below; whether each satisfies the contract is a re-audit, not done -here. - -## Hook plugins (9) — compliant - -Silent-always-on components: control is a `matcher` / `HOOK__ENABLED` kill-switch, not a -`userConfig`/setup surface; project conventions arrive through the consumer's own tool-config files -(`biome.json`, `.shellcheckrc`, `.editorconfig`, …), never `CLAUDE.md`. No setup action required; no -MCP; contract tests are `.test.sh`, not evals. - -| Plugin | Verdict | -|---|---| -| actionlint | compliant | -| bash-lint | compliant | -| biome-format | compliant | -| eol-normalizer | compliant | -| markdown-formatter | compliant | -| powershell-format | compliant | -| ruff-format | compliant | -| desktop-notification | compliant | -| guardrails | compliant — further in-repo hook migration into it owned by #1391 | - -## Pure-reference plugins (2) — no-op - -Knowledge-only skills; each README declares "no `userConfig` … pure knowledge skill". No config seam, -no hooks, no repo coupling — nothing to retrofit on the extensibility axis. - -| Plugin | Verdict | -|---|---| -| playbooks | no-op grade carried from the pre-merge `boris`/`thariq-skills`/`fable-5-playbook` — **class pending re-grade**: the merge adds an `update` mutation skill, which may move the plugin from pure-reference to behavior (the extensibility no-op may still hold — it exposes no config seam) | -| tdd | no-op | - -## Behavior plugins (28) - -| Plugin | Config seam | Setup | Ladder | MCP-carry | Evals | Verdict / owner | -|---|---|---|---|---|---|---| -| bug-report | `userConfig` `output_dir` | **missing** | default → plugin-data | — | present | **GAP → net-new setup issue** | -| claude-ops | `userConfig` `registry_dir` + `.claude/observability/` | **missing** | default → plugin-data | ccusage (CLI-first) | absent → #1396 | **GAP → net-new setup issue** (coordinate with #1391's claude-ops telemetry seam) | -| code-tidying | tracked `.claude/tidy-lanes/**` (seam 2, folder) | **missing** | ships default lanes; consumer overrides | — | present | **GAP → net-new setup issue** (scaffold project lanes) | -| songwriting | tracked `songwriting/templates/**` override + `${CLAUDE_PROJECT_DIR}/songwriting/` output (seam 2/3) | **missing** | safe default layout + CLAUDE.md precedence; ships default templates, consumer overrides | Datamuse public API (rhyme, no secret, opt-in) | absent → #1396 | **GAP → net-new setup issue** (scaffold project template overrides). Reclassified from pure-reference: 9 action skills (`rhyme`/`co-write`/`suno`/…), not knowledge-only | -| discovery | tracked `.claude/topic-docs.yaml` (seam 2, shared concern file) | present | concern file → CLAUDE.md → infer/ask → default | perplexity/ref/microsoft-learn declared, not shipped (rule 3) | setup covered by shared convention eval | compliant | -| planning | tracked `.claude/topic-docs.yaml` (seam 2, shared concern file) | present | concern file → CLAUDE.md → infer/ask → default | — | present | compliant | -| implementation | tracked `.claude/topic-docs.yaml` (seam 2, shared concern file) + ecosystem commands | present for ecosystem commands; consumes the shared topic-docs and lifecycle artifact contracts | concern file → CLAUDE.md → infer/ask → default | — | present | compliant | -| codebase-health | tracked `.claude/codebase-health.md` (seam 2) | present | read-existing → interview → write | — | present | compliant (setup exemplar) | -| knowledge | `userConfig` `library_dir` | present | validate rendered value → `/plugin configure` when needed | — | absent → #1396 | compliant; setup never edits `pluginConfigs`; youtube/course-digest retrofits owned by #1408/#1409 | -| machine-health | `userConfig` `report_dir` + machine-local overlay | present | overlay persisted; personal scalar delegated to `/plugin configure` | — | absent → #1396 | compliant setup ownership; remaining behavior fixes owned by #1419 | -| skill-quality | `userConfig` `skills_root` | present | validate/infer candidate → `/plugin configure` when needed | — | absent → #1396 | compliant; setup never edits `pluginConfigs`; runner/contract work owned by #1418 | -| claude-config | consumer `.claude/**` via `CLAUDE_PROJECT_DIR` (seam 3) | n/a | reads consumer config | — | present | compliant | -| context7 | none needed | n/a | — | ctx7 (CLI-first) | absent → #1396 | compliant | -| firecrawl | none needed | n/a | — | firecrawl-cli (CLI-first) | absent → #1396 | compliant | -| playwright | none needed | n/a | — | @playwright/cli (CLI-first) | absent → #1396 | compliant | -| work-items | tracked `.github/recurring-schedule.json` (seam 2, optional) + backend-neutral `gh` | **partial** | `recheck` requires it; `add --recurring` scaffolds a skeleton (ask-gated); no dedicated re-runnable setup | MCP-neutral (gh CLI) | present | **GAP → net-new setup issue** (dedicated setup for the recurring schedule) | -| event-storming | none needed | n/a | — | miro STAY (degraded-but-functional) | absent → #1396 | compliant; miro reconcile owned by #1405 | -| review | tracked `.claude/topic-docs.yaml` (seam 2, shared concern file — `memory_dir`) + consumer rules (seam 3) | n/a | concern file → CLAUDE.md/rules → default | — | absent → #1396 | compliant; ecosystem-commands retrofit owned by #1421 | -| session-flow | tracked `.claude/topic-docs.yaml` (seam 2, shared concern file — `memory_dir`) | n/a | concern file → CLAUDE.md/rules → default | — | absent → #1396 | compliant | -| source-control | writes `.claude/worktrees/` (default) | n/a | safe default | — | absent → #1396 | compliant | -| debugging | none needed | n/a | — | — | absent → #1396 | compliant | -| docs-hygiene | none needed | n/a | — | — | absent → #1396 | compliant | -| architecture | none needed | n/a | — | — | present | compliant | -| mcp-tools | none needed | n/a | — | — | present | compliant | -| prototype | none needed | n/a | — | — | absent → #1396 | compliant | -| repo-hygiene | none needed | n/a | — | — | present | compliant | -| education | none needed (seam 3) | n/a | — | — | absent → #1396 | compliant | -| kindle-dedrm | none needed (own state) | n/a | — | — | absent → #1396 | compliant | - -## Pending contract re-grade (added 2026-07-15) - -These plugins carry no 2026-07-12 grade — four are reorg split-offs; `ai-briefing` was never graded. -Only the empirical columns below were verified this session (config-seam presence from `plugin.json` -and the skill tree, eval presence from the live scan); the contract **verdict is unresolved** pending -a re-audit against the four-seam contract. The split-offs inherit context from their source -(`toolchain`/`testing`/`verification` from `implementation`; `claude-memory` from -`claude-config-audit`) — a starting point for that audit, not a substitute for it. - -| Plugin | Origin | Config seam (observed) | Setup skill | Evals | Verdict | -|---|---|---|---|---|---| -| toolchain | split from `implementation` (build, lint, setup) | `userConfig` absent; consumes the ecosystem-commands contract | present | present | **pending re-grade** | -| testing | split from `implementation` (test-\* → plan, write, e2e, diagnose) | `userConfig` absent | absent | present | **pending re-grade** | -| verification | split from `implementation` (verify-\* → confirm, measure) | `userConfig` absent | absent | present | **pending re-grade** | -| claude-memory | split from `claude-config-audit` (memory-health → health) | `userConfig` absent; reads consumer `.claude/**` (seam 3, inherited) | absent | present | **pending re-grade** | -| ai-briefing | pre-existing, never graded | `userConfig` `active_profile` (seam 1) | present | present | **pending re-grade** — a `userConfig` seam requires a setup action (present); compliance unverified | - -## Net-new retrofit issues emitted - -One `retrofit()` issue per setup-action gap, sub-issue-linked under wave-2 map -`melodic-software/medley#1369`, `agent-ready`. Each is scoped to: add a re-runnable -`setup`/`configure` skill that interviews the consumer and writes the appropriate owned config -(a tracked project instruction/config file or machine-local plugin state). Personal `userConfig` is -owned by Claude Code's native plugin configuration surface; setup validates it but never writes -`pluginConfigs`. The setup remains idempotent per the playbook's -"Setup action — every configurable plugin ships one", and bump `plugin.json` `version`. - -Frozen 2026-07-12 record. Per the 2026-07-15 scan, a `setup` skill dir is now present for all seven -(`bug-report`, `claude-ops`, `code-tidying`, `discovery`, `planning`, `work-items`, `songwriting`) — -the retrofit issues appear to have landed. Whether each shipped setup satisfies the contract is a -re-audit, not recorded here. - -| Plugin | Issue | -|---|---| -| bug-report | melodic-software/medley#1428 | -| claude-ops | melodic-software/medley#1432 (coordinate with #1391) | -| code-tidying | melodic-software/medley#1431 | -| discovery | melodic-software/medley#1429 | -| planning | melodic-software/medley#1430 | -| songwriting | melodic-software/medley#1433 | -| work-items | melodic-software/medley#1435 |