@mlmcps/ml-specs-mcp 1.0.0

package/commands/spec-build.md

@@ -0,0 +1,66 @@
+---
+description: Implement a feature strictly against an approved spec, test-first
+argument-hint: <path to spec file, e.g. specs/0001-foo.md> — or several, to build in parallel
+---
+
+You are in the **IMPLEMENT** phase of spec-driven development.
+
+Spec: **$ARGUMENTS**
+
+The spec is the contract. Anything not in it is out of scope — if a gap surfaces, the spec gets
+updated first, then the code. Never the other way round.
+
+Steps:
+
+1. **Read the spec in full**, plus `CLAUDE.md` and `docs/PATTERNS.md`, and detect the stack (any
+   language) from the manifest/build file. Check its Status is `Approved` — if it's still `Draft`,
+   say so and stop; building an unapproved contract is how rework happens.
+
+   Note the difference between the two knowledge sources the agent will use: `docs/PATTERNS.md`
+   **describes** how this repo happens to write code, and the architecture standards
+   (`.mlskills.json` + the `ml-skills` server) **prescribe** how it must. When they disagree, the
+   doc is the one that is out of date — the developer agent is told to flag the divergence rather
+   than copy local style, and that flag is a finding for you to relay, not noise to suppress.
+
+2. **Resolve gaps before delegating.** If something the implementation needs isn't in the spec,
+   STOP and put it to the user with the AskUserQuestion tool as concrete options with a
+   recommendation. Update the spec (with a **Revisions** row) before any code is written. Do this
+   here, in the main thread — a subagent has no channel to the human, so an unresolved gap becomes
+   a guess the moment you hand off.
+
+3. **Present a short implementation plan** (plan mode) and get approval before any edits.
+
+4. Use the **developer** agent to implement it — one agent per spec. Give it the spec path
+   and the approved plan; its own instructions carry the discipline (test per acceptance criterion,
+   a functional/E2E test for every user-facing or contract-level one, targeted tests during the
+   loop, the full final-acceptance suite once at the end, real results only). Don't restate those
+   rules — and don't implement inline instead, or the work silently loses the agent's guarantees.
+
+   **Several specs at once?** Spawn one `developer` per spec, each in **its own git worktree**,
+   and run them concurrently — that's the three-developers pattern in `specs/AGENTS.md`. Only do
+   this for specs that don't touch the same files; sequence coupled ones instead, because paper
+   conflicts are cheaper than merge conflicts.
+
+5. **Relay what the agent returns, unsoftened** — the file list, the real test output, and anything
+   it flagged as wrong in the spec. If it reports a failing suite, report the failure; never
+   convert "it built" into "it works". If it surfaced a spec gap, go back to step 2.
+
+6. **Advance the spec:** `/spec-advance <spec-file> Implemented` — that command re-checks each
+   criterion's named test actually exists and records the branch, so the status is evidence-backed
+   rather than self-declared.
+
+7. **Then the VERIFY phase, in this order:**
+   - `/spec-verify <spec-file>` — the `reviewer` agent judges the implementation against the
+     spec's acceptance criteria and runs the final-acceptance suite. This is the gate for
+     `Verified`; do not set that status yourself.
+   - `/code-review` (and `/security-review` if auth/data exposure is involved) — these check the
+     diff for bugs, a different question from "does it match the spec". Run both.
+   - `/spec-advance <spec-file> Verified` once they're clean, then `/pr <spec-file>` for the PR text.
+
+Keep the spec in the same branch/PR as the implementation, follow the repo's branch-naming and
+commit conventions, and only commit/push when the human asks.
+
+When you do commit, the message names the humans who own the change and nothing else — no
+`Co-Authored-By:` line for an assistant, no "Generated with"/"Made with" line, no model or vendor
+name, no tool badge or emoji. This applies to every commit on the branch: a squash merge aggregates
+trailers from all of them, so one stray line resurfaces on the merge commit.

package/commands/spec-fanout.md

@@ -0,0 +1,64 @@
+---
+description: One spec, N repos, N pull requests — find who else a contract change breaks, then open a branch and PR in each, all carrying the same key
+argument-hint: `<spec-id> <contract...>` — e.g. `0031 payment.captured "POST /payments/{id}/capture"` · add `--dry-run` to read the requests first
+model: sonnet
+---
+
+Fan a spec out across the services it actually touches: **$ARGUMENTS**
+
+A change spanning four services is four pull requests that a reviewer correlates
+by hand and hopes they got right. Every branch here is the same derived name, so
+the four are provably one change — and the impact query finds the service one hop
+out that nobody remembered.
+
+## 1. Plan before you open anything
+
+```
+node ${CLAUDE_PLUGIN_ROOT}/scripts/spec-fanout.mjs <spec-id> <contract...> --plan
+```
+
+That reads `docs/ESTATE.md` and prints the targets with a reason each: named on
+the spec, consumes a changed contract, or one hop further out. It opens nothing.
+
+**Stop and show the user this plan.** Two things are worth their attention before
+anything is created:
+
+- **A repo they did not expect.** That is the query doing its job, and it is also
+  the most common moment to discover the estate index is stale. If a name looks
+  wrong, run `/repo-estate` before fanning out — a stale graph reports confidently
+  that nothing else breaks, which is worse than no graph.
+- **A repo missing that they did expect.** Same cause, opposite symptom.
+
+## 2. Dry run
+
+```
+node ${CLAUDE_PLUGIN_ROOT}/scripts/spec-fanout.mjs <spec-id> <contract...> --dry-run
+```
+
+Prints the exact branch-creation and pull-request calls that would be sent, and
+sends none of them. This is what you hand to whoever owns the organisation when
+asking for a token.
+
+## 3. Open them
+
+Drop `--dry-run` once the user has agreed to the plan. Credentials come from the
+environment (`ADO_ORG`/`ADO_PROJECT`/`ADO_PAT`, or `GITHUB_OWNER`/`GITHUB_TOKEN`
+with `SDD_SCM_TOOL=github`) — never from a file in the repo.
+
+## What can go wrong, and what to say
+
+- **`spec … is Draft; no branch is cut before the approval gate`** — correct
+  behaviour, not a bug. The contract is still being negotiated. Point at
+  `/spec-advance`.
+- **Some repos opened, some failed.** Expected and reported, never thrown: a
+  permissions error on the fourth repo must not hide that three succeeded. Report
+  which failed and why. Re-running is safe for the ones that worked only if their
+  branches do not already exist — say so rather than guessing.
+- **`branches diverged — not one change`** — the fan-out lost its shared name.
+  That defeats the whole point; stop and investigate rather than merging.
+
+## Close
+
+Tell the user the branch name, how many pull requests are open, and that each
+body carries the acceptance criteria as a reviewer checklist. If any repo failed,
+lead with that.

package/commands/spec-review.md

@@ -0,0 +1,24 @@
+---
+description: Adversarially review a draft spec BEFORE any code — checks contracts, acceptance criteria, and cross-module ripple are complete and testable
+argument-hint: <path to spec file, e.g. specs/0001-foo.md>
+---
+
+Spec: **$ARGUMENTS**
+
+Use the **spec-reviewer** agent to review this spec adversarially, before any code exists. It
+runs read-only and with fresh context — it reports what needs changing rather than editing the spec.
+
+`/spec` already runs this pass on every spec it writes. Reach for this command when the spec was
+written by hand, was edited substantially since it was drafted, or came from someone else.
+
+Relay the agent's verdict: the per-check results, the must-fix list, and its final **approve** /
+**revise** / **split** call. Separate the must-fixes the agent says are resolvable from the code
+from the ones needing a human contract decision — offer to fix the first group, and put the second
+to the user with the AskUserQuestion tool as concrete options with a recommendation, not as open
+questions.
+
+Do not start implementation, and do not change the spec's Status — that's `/spec-advance`. After a
+clean review and the human's approval: `/spec-advance <spec-file> Approved` → `/spec-build <spec-file>`.
+
+(This reviews the **paper**. Its counterpart, `/spec-verify`, reviews the **code** against that
+paper once it's built.)

package/commands/spec-verify.md

@@ -0,0 +1,55 @@
+---
+description: Adversarially verify an implemented change against its spec's acceptance criteria, and run the final-acceptance suite — read-only, decides whether the spec can be Verified
+argument-hint: <path to spec file, e.g. specs/0001-foo.md>
+---
+
+Spec: **$ARGUMENTS**
+
+You are in the **VERIFY** phase of spec-driven development. This command is **read-only** — it
+judges the implementation, it does NOT fix it.
+
+Use the **reviewer** agent to review the current branch/diff against this spec. It runs with
+fresh context, so it judges the code against the written contract rather than against the intent
+of whoever wrote it.
+
+This is not a substitute for `/code-review` — they answer different questions and you want both:
+
+| | Question it answers |
+|---|---|
+| `/spec-verify` (this) | Does the implementation satisfy **this spec's** acceptance criteria, each with a test that would fail on regression? |
+| `/code-review` (built-in) | Is the **diff** itself correct — bugs, edge cases, simplifications — regardless of any spec? |
+
+**If the change touches a published contract** (an event payload, an API request/response shape,
+shared data, an exported package type), also run `/repo-impact <spec-file>` — neither this review nor
+`/code-review` looks outside this repo, so a change that breaks a consumer passes both cleanly.
+
+Relay the agent's verdict without softening it:
+- The **per-acceptance-criterion table**: satisfied / not satisfied / **untested** (implemented but
+  with no test that would fail if the behavior regressed, or a user-facing criterion covered only
+  by a unit test with no functional/E2E test).
+- The **must-fix list**, each with `file:line`.
+- The **final-acceptance result** (spec §6.1) — the real command and its real output. If the suite
+  could not be run, say so explicitly; never report an unrun suite as green.
+- The **architecture standards result** — from **`verify_evidence`** on the `ml-skills` MCP server,
+  with `base` set to the branch this work forked from so findings are scoped to what this change
+  actually touched. Report its `verdict` verbatim: `fail`, `pass`, `partial`, or `inconclusive`.
+  **`inconclusive` means clean but nothing was ratified, so nothing could have failed — it is not a
+  pass**, and rounding it to one is how a gate goes decorative without anyone noticing. Findings in
+  files this diff did not touch are pre-existing, not this change's problem — say so rather than
+  turning the review into a cleanup project. If ml-skills is not installed, report the standards
+  verdict as **unavailable**; an unrun check is not a clean one.
+
+Then split the must-fixes into two groups and act:
+1. **Code fixes** — the implementation doesn't match the approved spec. Offer to fix them
+   (`/spec-build` or the `coder` agent), then re-run this command.
+2. **Spec gaps** — the code is right and the *spec* is wrong or silent. That is a contract change:
+   put it to the user with the AskUserQuestion tool as concrete options with a recommendation.
+   Update the spec (with a **Revisions** row) before touching code. Never quietly widen the spec to
+   match what was built.
+
+Next step:
+- **Clean** (every criterion satisfied, functional/E2E present for the user-facing ones, full suite
+  green, no new error-severity standards finding) → `/spec-advance <spec-file> Verified`, then
+  `/pr <spec-file>`.
+- **Not clean** → fix, then re-run `/spec-verify <spec-file>`. Do not advance the spec's status and
+  do not open a PR on a failing verdict.

package/commands/spec.md

@@ -0,0 +1,73 @@
+---
+description: Draft a spec-driven-development spec for a feature/ticket (no implementation)
+argument-hint: <ticket-id or short feature description>
+---
+
+You are in the **SPECIFY** phase of spec-driven development. Your job is to produce a
+specification document — **do NOT write any implementation code in this phase.**
+
+Feature / ticket: **$ARGUMENTS**
+
+Aim for a spec the human can approve in **one pass**. Every blocking question you leave in the
+document costs them a read, a revision, and a re-read — so resolve those up front, and let an
+adversarial pass find the holes before the human does rather than after.
+
+Steps:
+
+1. Detect the stack (any language) from the manifest/build file and existing source, then read
+   `CLAUDE.md`, `docs/PATTERNS.md`, and `specs/README.md` so you follow this project's conventions.
+
+2. Explore the relevant code to ground the spec in reality (current behavior, the affected
+   module/component/bounded context, the data/API contracts, relevant events or cross-module
+   calls). Cite real `file:line` references.
+
+3. **Resolve blocking ambiguity BEFORE writing — never defer it into the document.** A question is
+   **blocking** if its answer would change a contract: API shape, data model or migration,
+   error/status codes, scope boundary, or backward compatibility. Rule of thumb: if knowing the
+   answer would make you rewrite a section, it's blocking.
+   Ask all of them in **one batch** with the AskUserQuestion tool — never one at a time, and never
+   as open prose. Each question gets concrete options grounded in the code you just read, your
+   recommendation first, and a line on what choosing it means. The user should be able to accept
+   your defaults in seconds.
+   A question whose answer changes **nothing** in this spec (a later optimization, something for
+   another team) is not blocking — that goes in section 8, and only that.
+
+4. Copy `specs/TEMPLATE.md` and fill every section, using the answers from step 3. Make acceptance
+   criteria concrete and testable (Given/When/Then), and map each AC to a planned test for this
+   project's stack. (If `specs/` or `specs/TEMPLATE.md` is missing, the repo hasn't been set up —
+   tell the user to run `/repo-init` first, or fall back to the plugin template at
+   `${CLAUDE_PLUGIN_ROOT}/templates/specs/TEMPLATE.md`.)
+
+5. **Actually create the file** — use the Write tool to save it as `specs/NNNN-<slug>.md`,
+   creating the `specs/` directory if it doesn't exist. Do NOT just print the spec in chat — it must
+   land on disk.
+
+   **Pick NNNN from every branch, not just this one.** The next number after the highest that
+   exists *anywhere*, or two people speccing in parallel both get `0007-` and find out at merge:
+
+   ```
+   git log --all --pretty=format: --name-only --diff-filter=A -- 'specs/[0-9]*' | sort -u
+   ```
+
+   Union that with the working tree (`specs/` and `specs/archive/`) and take max + 1. If the repo
+   has a remote, `git fetch --quiet` first so branches you haven't pulled are counted too — and if
+   the fetch fails (offline, no remote), say so and note the number may collide, rather than
+   quietly numbering off a stale view.
+
+6. **Adversarial pass before the human sees it.** Spawn the **spec-reviewer** agent on the file
+   you just wrote. It reads with fresh context and will catch contract gaps and untestable criteria
+   you cannot see, because you wrote them. Fix every **blocker** and **needs-work** item it returns.
+   If a fix needs a human contract decision, batch it back through AskUserQuestion (step 3) — do
+   not write it into section 8 instead. Re-run the reviewer only if you made substantial changes.
+
+7. Summarize for the user: the spec path, the contract decisions taken, cross-module impact, and
+   what the reviewer flagged and you fixed. Then **ask them to review/approve.** On their approval,
+   record it with `/spec-advance specs/NNNN-<slug>.md Approved`; the next step after that is
+   `/spec-build specs/NNNN-<slug>.md`. Leave the Status at `Draft` yourself — you don't approve
+   your own spec.
+
+**If the user sends the spec back for changes:** update the file, add a row to its **Revisions**
+table recording what changed and why, and point them at that row. They should only have to re-read
+what moved — not the whole document.
+
+Keep the spec tight and honest. Flag risks and cross-service impacts explicitly.

package/mcp/README.md

@@ -0,0 +1,173 @@
+# ml-specs MCP server
+
+The **deterministic** half of the toolkit, exposed over MCP so any client — Claude Code, Cursor, a
+custom agent, a CI script — can use it without a model in the loop.
+
+Everything here is **read-only**. No tool writes, moves, or deletes anything.
+
+## What ports, and what doesn't
+
+Skills and hooks have no MCP equivalent: MCP cannot register a `SessionStart` or `PreToolUse`
+hook, and it cannot spawn a subagent with its own tool allowlist and model. Those stay in the
+plugin, and so does the real subagent execution the commands rely on.
+
+Two things do port. First, the computation — the parts that read files and return facts, where a
+model adds nothing:
+
+| Tool | Answers |
+|------|---------|
+| `estate_lookup` | Who produces/consumes this contract? (from `docs/ESTATE.md`) |
+| `knowledge_check` | Do the docs still match the code — every `file:line`, link, and shard? |
+| `spec_list` | What specs exist, at what status, with how many criteria met? |
+| `spec_next_number` | What's the next free spec number **across all branches**? |
+| `spec_gate` | Does this spec have the mechanical evidence for its next status? |
+| `spec_trace` | Is the id chain from ticket to test case intact, for one spec or all? |
+| `spec_brief` | The approved spec packaged for whoever implements it (markdown) |
+| `nfr_check` | Which non-functional requirements do **not** route into something enforceable? |
+| `estate_survey` | What state are the neighbouring repos in, before spending `/repo-init` on them? |
+
+The last five are `scripts/` exposed. They were the half of the toolkit that most needed to be
+reachable from outside Claude Code and least was: `spec_gate` is the lifecycle gate itself, so
+until now a CI job could not ask the one question the whole loop turns on — *does this spec have
+the evidence for `Verified`?*
+
+They are **invoked as subprocesses, not imported**. The scripts parse their arguments at module top
+level, so importing one would run its CLI — but invoking is also the stronger no-drift guarantee.
+An imported function can diverge from the CLI in argument handling and defaults; a subprocess is
+the same execution path a human gets. One process spawn per call is nothing for a read-only tool.
+
+Read-only holds **by construction**: `--apply`, `--out` and `--gates` are never passed, there is no
+parameter that could smuggle one in, and a test asserts those flags do not appear anywhere in the
+dispatch. Writing stays in the plugin, where a human approves it.
+
+Two behaviours worth knowing, because both are deliberate:
+
+- **A failed gate is a result, not an error.** These scripts exit 1 to mean "the gate failed".
+  The tool returns the verdict with `exitCode: 1` rather than raising, because a legitimate `FAIL`
+  the caller cannot read is worse than no answer. Exit 2 — *could not run* — is still an error.
+- **`nfr_check` returns `present: false` when the repo has no `docs/NFRS.md`**, for the same reason
+  `estate_lookup` does: absent means the non-functional requirements are **unknown**, not that
+  there are none. Reporting "nothing failed to compile" would be a false all-clear on exactly the
+  requirements most likely to be agreed and then lost.
+
+Templates are also served as resources under `mlspec://templates/…`.
+
+Second, the **commands**, served as MCP prompts — all 18 of them, described from their own
+frontmatter, with `$ARGUMENTS` filled in at `prompts/get`. Clients namespace these, so `spec`
+arrives as `/mcp__ml-specs__spec` rather than `/spec`; that is the client's doing, not a choice
+made here.
+
+Where a command delegates to an agent, that agent's instructions are appended to the prompt as an
+appendix, because a client with no subagent mechanism would otherwise skip the step silently — a
+command that appears to run while quietly dropping its adversarial pass is worse than one that
+fails. Inline execution loses the isolated context, tool restrictions and parallelism the plugin
+gets. `/spec-fanout` degrades most, being parallel by design.
+
+`estate_lookup` returns `present: false` with an explicit note when the repo has no estate index.
+That distinction is the whole point: "no index" is not "no consumers", and a false all-clear on a
+cross-service change is worse than no answer, because it gets believed.
+
+## Run it
+
+```bash
+node ml-specs-server.mjs --root /path/to/the/repo     # stdio transport; --root defaults to cwd
+```
+
+No dependencies and no install step — stdio MCP is newline-delimited JSON-RPC 2.0, implemented
+directly here for the same reason `scripts/validate-plugin.mjs` has no dependencies: nothing in this
+repo is ever installed before it runs. The two `package.json` files exist only to *publish* — they
+declare no dependencies and there is no `node_modules`.
+
+## Sharing it with a team
+
+**First, the honest bit:** you cannot ship JavaScript to someone's machine and prevent them
+reading it. `node_modules` is source, and even a compiled single-executable can be unpacked. So
+pick based on what you're actually solving:
+
+| Goal | Do this | Cost |
+|---|---|---|
+| Teammates get **only these nine tools** | `@mlmcps/ml-specs-mcp` npm package (below) | Public on npmjs — anyone can read the package source |
+| Teammates get the **whole toolkit**, without repo access | `@mlmcps/ml-specs` npm package as the marketplace source | Public on npmjs; updates arrive on tag, not on merge |
+| Teammates get the whole toolkit **and** the repo | Private repo + `/plugin marketplace add` | They can clone everything, history included |
+| Genuinely no readable source | Single executable (`node --experimental-sea-config`, `bun build --compile`) | Per-platform builds; unpackable anyway |
+
+**Hosting it remotely does not work for this server** — and the reason is worth knowing. Every tool
+here answers questions about *the repo the caller is sitting in*. A remotely hosted server would
+inspect files on the server, not on the teammate's laptop, so it would return answers about the
+wrong repo. This server is local by design, not by omission.
+
+### Public npm package (recommended)
+
+The package ships `mcp/`, `scripts/` (the tools invoke them) and the one CI module it imports —
+zero dependencies, no agents, no templates. Since 0.19.0 it is **public on npmjs.org under
+MIT**, so a teammate needs no token, no registry config, and no access to this repo. The repo itself
+stays private; `files[]` is what keeps the rest of it out of the tarball.
+
+```bash
+# you, once per release — normally CI does this on a tag
+npm publish                       # publishConfig points at registry.npmjs.org, access public
+```
+
+Teammates configure nothing. In any repo they work in, `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ml-specs": {
+      "command": "npx",
+      "args": ["-y", "@mlmcps/ml-specs-mcp", "--root", "."]
+    }
+  }
+}
+```
+
+That file is safe to commit — it names a package, not a path on anyone's laptop.
+
+## Wire it into a repo
+
+Copy `../templates/mcp/.mcp.json` to that repo's root as `.mcp.json`, set the absolute path, and
+commit it — project-scoped config, so the whole team gets it. Or register it per-user:
+
+```bash
+claude mcp add ml-specs -- node /abs/path/to/ml-specs/mcp/ml-specs-server.mjs --root .
+```
+
+Verify with `/mcp` in Claude Code; the nine tools should be listed.
+
+## How updates reach people
+
+Which mechanism applies depends on how they got it — and the first case is the one most teams
+should be in, because it has no separate update step at all.
+
+**Installed as part of the plugin** (Claude Code users). The bundled `.mcp.json` resolves through
+`${CLAUDE_PLUGIN_ROOT}`, so the server is *inside* the plugin: when the marketplace updates the
+plugin, the server comes with it. With `autoUpdate: true` that's automatic on the next launch —
+restart Claude to pick it up. **There is nothing extra to publish or install.** If your whole team
+uses Claude Code, you do not need the npm package.
+
+**Installed from npm** (Cursor, custom agents, CI, or people who shouldn't get the whole plugin):
+
+| `.mcp.json` args | Update behaviour | Use when |
+|---|---|---|
+| `["-y", "@mlmcps/ml-specs-mcp@0.19.0", …]` | **Pinned.** Everyone runs exactly what you tested; bumping is a commit teammates can review. | A team — recommended |
+| `["-y", "@mlmcps/ml-specs-mcp", …]` | Resolves the latest at launch, so a new session can silently change versions. | Solo, or you want the newest always |
+
+Servers start per session, so either way a **restart** is what applies an update — nothing hot-reloads.
+
+**Which version is actually running?** Version skew across a team is the predictable failure here
+(one stale npx cache, one freshly-updated plugin, two different answers). Ask it directly:
+
+```bash
+npx @mlmcps/ml-specs-mcp --version     # or: node .../mcp/ml-specs-server.mjs --version
+```
+
+It prints the version *and the resolved file path*, so "which copy is this" is answerable in one
+line. The same version is reported in the MCP handshake, and the repo's validator keeps all five
+places it's written from drifting.
+
+## Relationship to the plugin
+
+They compose — install both. The plugin gives you the loop (`/spec` → … → `/pr`), the agents, and
+the hooks; this gives every tool the same facts underneath. `knowledge_check` shares one
+implementation with the CI gate in `../templates/ci/knowledge-check.mjs`, imported rather than
+copied, so the two can't drift apart.