Repository navigation
feat: markdown-formatter plugin (pilot migration) - #3
Conversation
Add .editorconfig (LF, 2-space, shfmt shell keys) and .shellcheckrc (external-sources, source-path=SCRIPTDIR, selective optional checks), mirroring the standards/medley drop-in configs. Governs authoring and linting of this repo's own shell sources only; not shipped to plugin consumers. Long-term these should be consumed from the standards repo. Co-Authored-By: Claude <noreply@anthropic.com>
PostToolUse hook that auto-formats and lints Markdown on edit via markdownlint-cli2 --fix, using the consuming repo's own markdownlint config (ships none). Lifted and genericized from melodic-software/medley's in-repo markdown-format hook: telemetry/observability coupling removed, medley-policy wrapper prose dropped, file-anchored repo-root cd preserved for config discovery, kill switch HOOK_MARKDOWN_FORMAT_ENABLED retained. No userConfig. Bundles a trimmed hook-utils subset and a black-box contract test (12 cases). Verified: claude plugin validate --strict; --plugin-dir load in a clean non-medley repo; source-repo parity vs the in-repo hook (byte-identical --fix output, MD024 finding-line identity, zero plugin telemetry). Co-Authored-By: Claude <noreply@anthropic.com>
Add the markdown-formatter entry to .claude-plugin/marketplace.json so the already-committed plugin is installable, and surface it in the README catalog. Drop metadata.pluginRoot: claude plugin validate --strict rejects the bare plugin source it is meant to enable (plugins.N.source: Invalid input), despite the marketplaces-doc example. Entries use the explicit ./plugins/<name> form. Playbook step 10 now records the ./-prefixed-source requirement and the need to validate the catalog manifest itself (the entry error surfaces only there). Co-Authored-By: Claude <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b970d0c306
ℹ️ 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".
| local norm_file norm_project | ||
| norm_file=$(hook::normalize_path "$file") | ||
| norm_project=$(hook::normalize_path "${CLAUDE_PROJECT_DIR}") | ||
| if [[ "$norm_file" != "$norm_project"* ]]; then |
There was a problem hiding this comment.
Require a path boundary for project membership
When CLAUDE_PROJECT_DIR is /repo/app, this raw prefix check also accepts /repo/app-backup/file.md. The guard is supposed to skip files outside the current project, but with similarly named sibling directories a Write/Edit to that path will still run markdownlint-cli2 --fix outside the project; compare against $norm_project/ or use a relative-path check with a real boundary.
Useful? React with 👍 / 👎.
| elif command -v npx >/dev/null 2>&1; then | ||
| MDLINT=(npx markdownlint-cli2) |
There was a problem hiding this comment.
Avoid treating npx alone as an available formatter
In repos where npx exists but markdownlint-cli2 is not installed locally/globally and the npm registry is unavailable or blocked, this branch still runs npx markdownlint-cli2; npx --help describes it as running from a “local or remote npm package”, so the hook captures npm fetch failures and reports them as markdownlint findings on every Markdown edit instead of being a no-op. Check for an actually local/resolvable package or suppress this fallback when the package cannot be executed without fetching.
Useful? React with 👍 / 👎.
…r self-contained Address three more Codex P2 findings: - teach topic case (#1): topic is start-or-resume, so a fresh-workspace expectation flakes on a machine with prior data. Assert the start-or-resume contract — mission interview for a new workspace, resume for an existing one. - teach primer case (#3): the primer intakes the user's starting point with one question before building the ladder, so a single-turn run may correctly open with the intake. Make the expectation intake-first. - diagnose cleanup case (#6): a broad grep -r "[DEBUG-" already matches the diagnose docs and this fixture in the checkout. Scope the assertion to the specific [DEBUG-a4f2] tag across the changed source.
… 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 -->
… 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>
#218) ## Summary `code-tidying:tidy`'s Phase H ("Ship") told the agent to create the PR by calling `gh pr create` directly — a bare bypass of `source-control:pull-request`'s canonical create flow, which resolves issue-linkage (with an issue-existence check before shipping a `Closes #N` keyword), assembles the PR body injection-safely (quoted heredoc + parameter-expansion concat, a defense against shell injection through prompt-derived text), and gates PR creation on a valid closing keyword or explicit opt-out before calling `gh pr create` itself. Closes decisions **#3** and **#42** of the melodic-software issue/PR consistency initiative's Decisions Log (`https://claude.ai/code/artifact/232ecdce-8316-4880-8c0a-dc3c7dcf3a63`): - **#3 (formatting-tidy-canonical-pr-gate-bypass)** — "YES, fix — but not via direct skill-to-skill coupling... minimize coupling between `code-tidying:tidy` and `source-control:pull-request`... Likely shape: a shared script/check both skills call, or a convention-level requirement enforced by a common gate." This PR fixes the bypass without a hard cross-plugin dependency (below). - **#42 (crosscut-skill-content-sync-mechanism)** — "Single shared reference doc, all authoring skills import it." Applied here for its first concrete instance (see Design rationale). ## What changed Phase H now applies the same optional-plugin graceful-degrade pattern `tidy` already uses elsewhere in its own SKILL.md (Phase C for `discovery`, Phase D for `work-items`): - **If `source-control` is installed:** invoke `/pull-request create`, supplying tidy's own title/body-section content. Its stage-and-commit step (§2.3) is a no-op here since Phase E already committed the tidyings atomically — the call goes straight to rebase-check, issue-linkage resolution, and gated PR creation. - **If `source-control` isn't installed:** the same invariants apply inline — verify an issue exists before writing `Closes #N`, assemble the body via quoted heredoc + concat (never an unquoted `<<EOF`), and refuse `gh pr create` until the body carries a valid closing keyword or an explicit `Refs #N` / `No related issue:` opt-out. ## Design rationale (decision #42, recorded as an assumption — no user available to confirm interactively this session) Considered extracting the safety invariants into a new shared reference doc (mirroring the `docs/PLUGIN-ARTIFACT-PROTOCOL.md` → per-plugin `reference/artifact-protocol.md` precedent, drift-checked by `validate-plugin-contracts.mjs` and this session's new `scripts/check-cross-plugin-source-drift.sh`). Rejected for now: every invariant worth stating is already authoritative in `pull-request/reference/create.md`, so a copied doc would be pure duplication with drift risk — and with exactly one non-`source-control` consumer today, it wouldn't even register as a cluster for the new drift checker (which requires 2+ plugin copies). A prose convention pointer is lighter, carries no duplication to drift, and degrades gracefully if `source-control` is absent — which a hard-copied doc wouldn't buy any safety over. This is decision #42's design choice for its *first application*, not a retrofit of every authoring skill in the marketplace — no other skill is touched by this PR. Rolling the same pattern out to other PR-creating skills (if any surface a similar bypass) is deferred, unscoped follow-up work, tracked in the Decisions Log rather than guessed at here. ## Test plan - `bash scripts/validate-plugins.sh` — all plugin manifests + strict catalog validation pass. - `node scripts/validate-plugin-contracts.mjs` — 16 setup skills + 1342 plugin files checked, clean. - `npx markdownlint-cli2 plugins/code-tidying/skills/tidy/SKILL.md` — 0 errors. - Confirmed no other stale bare-`gh pr create` references remain under `plugins/code-tidying/`. - No existing test file exercises `tidy`'s `SKILL.md` prose directly (only `open-pr-count.test.sh`, unrelated to Phase H) — nothing to update there.
Tier 1 cues in history-narration, plan-reference and conversational-antecedent now need a whole-word start and end, so "used tokens", "per the planet", "replaces the older", "unchanged to" and "reformerly" no longer fire. A bare name#N (name of three or more characters) is ticket-pr-residue; "C#7", "F# 3" and "see section #3" are not. The marker exemption now requires TODO, FIXME, HACK or XXX as a whole word opening the comment or a clause, followed by "(" or ":". Every example row of the shapes table is a positive test, with one negative per cue. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EugXnFddtpHcY5gTuyEirB
First plugin migrated from medley into this marketplace — the pilot proving the end-to-end lift-and-shift pipeline.
What's in this PR
plugins/markdown-formatter/**— ported PostToolUse hook (markdownlint-cli2 on Write/Edit), bundledhook-utils.shsubset, black-box contract test (12/12), README (16faf60)..editorconfig+.shellcheckrc— platform drop-in configs (5bb2e77)..claude-plugin/marketplace.json— catalog entry making the plugin installable (was empty).README.md— catalog section listing the plugin.docs/MIGRATION-PLAYBOOK.md— step 10 records the./-prefixed source requirement + catalog-manifest validation.Verified
claude plugin validate --strict✔ on both the plugin and the marketplace manifest.--plugin-dirload smoke + source-repo parity (fresh-context) PASS.--plugin-dirand strict-validate do not exercise what a real marketplace install does: relative-source resolution (./plugins/markdown-formatter) and hook firing from the cache copy (~/.claude/plugins/cache). Prove both from this branch ref before merging:/plugin marketplace add https://github.com/melodic-software/claude-code-plugins.git#feat/markdown-formatter-plugin /plugin install markdown-formatter@melodic-software /reload-plugins # edit a .md with a fixable issue → confirm markdownlint-cli2 auto-fixesThis closes the recorded open gap (live in-session PostToolUse fire via an installed plugin). Merge → final user/global install from
main.Note: dropped
metadata.pluginRoot—claude plugin validate --strictrejects the bare source it is meant to enable, despite the marketplaces-doc example.