@mlmcps/ml-specs 1.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "ml-tools",
+  "owner": {
+    "name": "Motivity Labs",
+    "url": "https://github.com/MLMCPS"
+  },
+  "plugins": [
+    {
+      "name": "ml-specs",
+      "description": "Spec-driven development for any stack (Java/Spring, React, Node/Express, NestJS; MySQL/PostgreSQL/MongoDB): a stack-aware coding agent + spec author/developer/reviewer/pr-author agents, and the evidence-gated loop /spec, /spec-review, /spec-build, /spec-verify, /spec-advance, /spec-fanout, /pr, plus /code, /fix, /nfr and the knowledge layer /repo-init, /repo-rollout, /repo-adopt, /repo-estate, /repo-impact, /repo-refresh, /repo-doctor, /repo-status.",
+      "version": "1.0.0",
+      "source": "./ml-specs"
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ACE Online platform team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# 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`](ml-specs/) | Spec-driven development for any project: a stack-aware coding agent + spec author/developer/reviewer/pr-author/scanner agents; the gated loop `/spec` → `/spec-review` → `/spec-build` → `/spec-verify` → `/spec-advance` → `/pr`, plus `/code`, `/fix`, `/nfr` (routes NFRs into constraints + blocking gates), `/spec-fanout` (one spec, N repos, one key), `/repo-init` (learns the repo), `/repo-rollout`, `/repo-adopt`, `/repo-estate`, `/repo-impact` (who breaks if this ships), `/repo-refresh`, `/repo-doctor`, `/repo-status`; a knowledge-layer CI gate, hooks that ship active, and an [MCP server](ml-specs/mcp/) 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](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`](.github/workflows/release.yml), so they cannot drift:
+
+| Channel | Audience | How |
+|---|---|---|
+| **[`MLMCPS/ml-specs`](https://github.com/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 manifests + wiring; 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 /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/                 # coder, spec-author, spec-reviewer, developer,
+    │                           #   reviewer, pr-author, scanner
+    ├── commands/               # code, fix, spec, spec-review, spec-build, spec-verify, spec-advance, pr,
+    │                           #   repo-init/-rollout/-adopt/-estate/-impact/-refresh/-doctor/-status
+    ├── skills/                 # knowledge-retrieval (loads on demand)
+    ├── hooks/                  # active on install: drift warning + 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 /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.

package/ml-specs/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "ml-specs",
+  "description": "Spec-driven development for any stack (Java/Spring, React, Node/Express, NestJS; MySQL/PostgreSQL/MongoDB): a stack-aware coding agent + spec author/developer/reviewer/pr-author agents, and the evidence-gated loop /spec, /spec-review, /spec-build, /spec-verify, /spec-advance, /spec-fanout, /pr, plus /code, /fix, /nfr and the knowledge layer /repo-init, /repo-rollout, /repo-adopt, /repo-estate, /repo-impact, /repo-refresh, /repo-doctor, /repo-status.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Motivity Labs"
+  },
+  "homepage": "https://github.com/MLMCPS/ml-claude-plugins",
+  "repository": "https://github.com/MLMCPS/ml-claude-plugins",
+  "license": "MIT"
+}

package/ml-specs/.mcp.json

@@ -0,0 +1,17 @@
+{
+  "//": "MCP server bundled WITH the plugin. Because the path is ${CLAUDE_PLUGIN_ROOT}-relative,",
+  "//1": "it resolves wherever the plugin was installed from — a git marketplace, a local directory,",
+  "//2": "any machine. No absolute paths, so nothing here is specific to one developer's laptop.",
+  "//3": "",
+  "//4": "--root . means the server reads whichever repo the session is in. It is READ-ONLY and",
+  "//5": "makes no network calls: it answers questions about local files and returns nothing on its own.",
+  "//6": "",
+  "//7": "If a client does not pick this up automatically, fall back to copying",
+  "//8": "templates/mcp/.mcp.json into the target repo and filling in an absolute path.",
+  "mcpServers": {
+    "ml-specs": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/mcp/ml-specs-server.mjs", "--root", "."]
+    }
+  }
+}