ml-claude-plugins

Development repo for a Claude Code plugin marketplace. Ships stack-aware tooling (Java/Spring, React, Node/Express, NestJS; MySQL/PostgreSQL/MongoDB) — originally for a large microservice estate.

This repo is private; what it publishes is public. Development, tooling, examples and history stay here. Each release pushes the plugin itself to a public mirror and to npm, so anyone can install it without access to this repository.

Plugins

| Plugin | What it gives the team | |--------|------------------------| | ml-specs | Spec-driven development for any project: a stack-aware coding agent + spec author/developer/reviewer/pr-author/scanner agents; the gated loop /ml-specs:spec-explore (optional) → /ml-specs:spec → /ml-specs:spec-review → /ml-specs:spec-build → /ml-specs:spec-verify → /ml-specs:spec-advance → /ml-specs:pr, plus /ml-specs:code, /ml-specs:explain (what does this code actually do — a cited walkthrough), /ml-specs:fix, /ml-specs:handoff (a session handoff note, so the next session resumes instead of re-deriving), /ml-specs:nfr (routes NFRs into constraints + blocking gates), /ml-specs:spec-fanout (one spec, N repos, one key), /ml-specs:repo-init (learns the repo), /ml-specs:repo-rollout, /ml-specs:repo-adopt, /ml-specs:repo-skills, /ml-specs:repo-estate, /ml-specs:repo-impact (who breaks if this ships), /ml-specs:repo-refresh, /ml-specs:repo-doctor, /ml-specs:repo-status; a knowledge-layer CI gate, hooks that ship active, and an MCP server exposing the read-only tools and the commands as prompts to any client. |

Install

/plugin marketplace add MLMCPS/ml-specs
/plugin install ml-specs@ml-tools

That points at the public release mirror — no repo access, no org membership, no token. Add --scope user (the default) for every project on your machine, or commit the equivalent .claude/settings.json so a teammate gets it on clone.

Working on the plugin? Point at this repo instead, which updates on merge rather than on tag:

/plugin marketplace add MLMCPS/ml-claude-plugins
/plugin install ml-specs@ml-tools

Rolling it out to a team? → TEAM-SETUP.md — the per-repo auto-enable that scales across an estate, and the source types that do and don't work in a committed settings file.

Where it ships

Three channels, all published from one git tag ml-specs-vX.Y.Z by .github/workflows/release.yml, so they cannot drift:

| Channel | Audience | How | |---|---|---| | MLMCPS/ml-specs (public mirror) | Claude Code | /plugin marketplace add — the only source type that works from a committed .claude/settings.json | | @mlmcps/ml-specs-mcp (npm, MIT) | Cursor, VS Code, CI, custom agents | npx -y @mlmcps/ml-specs-mcp --root . in an MCP config | | @mlmcps/ml-specs (npm, MIT) | Vendored / air-gapped installs | npm install, then marketplace add <path> |

The mirror carries .claude-plugin/ and ml-specs/ and nothing else — byte-for-byte what the npm plugin package ships. scripts/, examples/, CONTRIBUTING.md, PUBLISHING.md, TEAM-SETUP.md, .github/ and this repo's history never leave it.

There is no npm marketplace source. Claude Code 2.1.121 accepts a marketplace as a URL, path, or GitHub repo only; a settings file declaring {"source": "npm", …} is silently ignored, with no error. The npm plugin package is published and ready for whenever the client supports it.

Layout

ml-claude-plugins/
├── .claude/commands/release.md # /release — cuts a plugin release (this repo only; not shipped)
├── .claude-plugin/
│   └── marketplace.json        # catalog of plugins (marketplace name: "ml-tools")
├── .github/
│   ├── workflows/              # CI: validate + test; release: npm publish + mirror push
│   └── mirror-README.md        # seed file for the public mirror repo (ships nowhere)
├── scripts/
│   ├── validate-plugin.mjs     # no-dependency validator (run locally + in CI)
│   └── changelog-section.mjs   # extracts a version's CHANGELOG section; gates the release
├── examples/                   # worked example of what /ml-specs:repo-init produces
├── CONTRIBUTING.md             # agent/command/skill/hook authoring conventions
├── LICENSE                     # MIT — applies from 0.19.0 onward
└── ml-specs/                # one plugin
    ├── .claude-plugin/plugin.json
    ├── agents/                 # analyst, coder, explainer, spec-author, spec-reviewer, developer,
    │                           #   reviewer, security-reviewer, pr-author, scanner
    ├── commands/               # code, explain, fix, handoff, spec-explore, spec, spec-review, spec-build,
    │                           #   spec-verify, spec-advance, pr, nfr, spec-fanout, repo-skills,
    │                           #   repo-init/-rollout/-adopt/-estate/-impact/-refresh/-doctor/-status
    ├── skills/                 # knowledge-retrieval (loads on demand)
    ├── hooks/                  # active on install: drift warning + handoff notice + secret scan
    ├── mcp/                    # read-only MCP server for any client (no dependencies)
    ├── scripts/                # spec-gate, fix-specs, spec-dashboard, survey-estate (pure Node)
    ├── templates/              # seeded into repos by /ml-specs:repo-init (specs, docs, ci/, mcp/, hooks)
    └── README.md

Releasing

Use /release — it does all of the below and refuses to leave the versions out of step.

• Five files carry the version and nothing keeps them in sync but the validator: plugin.json, ml-specs/package.json, the root package.json, the ml-specs entry in marketplace.json, and the VERSION constant in mcp/ml-specs-server.mjs.
• Every release needs a ## [x.y.z] section in ml-specs/CHANGELOG.md — changelog-section.mjs fails the workflow without one, so a version cannot ship undocumented.
• node scripts/validate-plugin.mjs must pass. It also fails the build if the plugin package's files[] widens: that list is a disclosure boundary now that the packages are public and this repo is not.
• Tagging publishes. npm publish cannot be undone after 72 hours, so every gate runs before it, and the mirror push runs last — if it fails, the packages are already out and only that step needs re-running.

Two repo secrets are required: NPM_TOKEN (an npm automation token — a classic publish token is rejected under 2FA) and MIRROR_TOKEN (a fine-grained PAT with Contents: write on the mirror repo only). The release skips the mirror with a message rather than failing if the second is absent.