Skip to content

feat: markdown-formatter plugin (pilot migration) - #3

Merged
kyle-sexton merged 3 commits into
mainfrom
feat/markdown-formatter-plugin
Jun 23, 2026
Merged

kyle-sexton merged 3 commits into
mainfrom
feat/markdown-formatter-plugin

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

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), bundled hook-utils.sh subset, 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-dir load smoke + source-repo parity (fresh-context) PASS.

⚠️ DO NOT MERGE until marketplace-install is proven from this branch

--plugin-dir and 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-fixes

This 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 --strict rejects the bare source it is meant to enable, despite the marketplaces-doc example.

kyle-sexton and others added 3 commits June 23, 2026 12:04
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>

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment on lines +28 to +29
elif command -v npx >/dev/null 2>&1; then
MDLINT=(npx markdownlint-cli2)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

@kyle-sexton
kyle-sexton merged commit abaf87e into main Jun 23, 2026
1 check passed
@kyle-sexton
kyle-sexton deleted the feat/markdown-formatter-plugin branch June 23, 2026 18:56
kyle-sexton added a commit that referenced this pull request Jul 12, 2026
…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.
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 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>
kyle-sexton added a commit that referenced this pull request Jul 16, 2026
#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.
kyle-sexton added a commit that referenced this pull request Sep 29, 2026
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant