@mlmcps/ml-specs 1.0.0

package/ml-specs/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/ml-specs/README.md

@@ -0,0 +1,347 @@
+# ml-specs
+
+Spec-driven development toolkit packaged as a Claude Code plugin, so every repo and every
+developer gets the same agents and commands. The agents are **stack-aware**: they detect the
+project before editing and follow its conventions — Java/Spring (Maven/Gradle), React, and
+Node backends (Express, NestJS), across MySQL, PostgreSQL, and MongoDB. (Originally built for
+a large microservice estate; works in standalone apps too.)
+
+## Why use this (vs. just asking Claude)
+
+Same model — the difference is what's wrapped around it. Default Claude Code re-learns your repo
+every session, infers conventions on the fly, jumps straight to code, and reports "done" with the
+human as the only check. This toolkit adds three things that change the outcome:
+
+1. **Durable, learned memory** — `/repo-init` studies the repo once and writes `CLAUDE.md` +
+   `docs/PATTERNS.md` + `docs/ARCHITECTURE.md` with real `file:line` evidence. Every later task
+   reads *your* conventions instead of re-guessing them, so output matches your codebase
+   consistently across sessions and developers.
+2. **Spec-before-code for non-trivial changes** — `/spec → review → /spec-build` puts the contract
+   (API, data model, cross-module ripple) on paper for human approval **before** code exists, so
+   the costly design errors get caught when they're a sentence to fix, not a rollback.
+3. **Discipline baked in** — a test per acceptance criterion, adversarial review against the spec,
+   "report real test results — never claim green," and tiered/sharded context so it stays cheap and
+   usable on large, interlinked codebases.
+
+| | Normal Claude Code | ml-specs |
+|---|---|---|
+| Knows your conventions | Re-guesses each session | Learned once, remembered |
+| Consistency across devs/repos | Varies per prompt | Same agents, format, specs |
+| Non-trivial change | Code first, find issues in the diff | Contract approved on paper first |
+| Verification | "Looks done" | Test per criterion + adversarial review |
+| Large / coupled codebase | Context bloat | Lazy-loaded, sharded, bounded |
+| Cost per task | Re-reads a lot | Thin index → only what's needed |
+
+**The trade-off:** more upfront ceremony (write/approve a spec, run `/repo-init` once, keep the docs
+fresh) in exchange for consistency, fewer wrong-contract surprises, and an agent that knows your
+code. Worth it for teams, multi-service estates, and long-lived codebases; **skip it** for one-line
+fixes and throwaway scripts — use `/code` (or plain Claude) there. The payoff is real only if the
+learned docs are accurate, which is why patterns carry `(inferred)` confidence markers and
+`/repo-init` flags them for a quick human review.
+
+## Token cost (set expectations before running on a big repo)
+
+The toolkit **front-loads** tokens to **cut** the per-task and rework tokens — so it pays off on
+repeated work and costs more on one-offs.
+
+**Spends more on:** `/repo-init` (a one-time codebase scan — the most expensive single op, biggest on
+large repos), the `/spec` phase (a doc before code), the per-task memory tax (`CLAUDE.md` + relevant
+`docs/` loaded each coding task), and the multi-agent loop (author → developer → reviewer are
+separate contexts — you're buying verification).
+
+**Saves on:** re-exploration (reads a small index instead of grepping the repo every session — the
+biggest recurring win on large repos), lazy/sharded loading (only the module a task touches, +1-hop
+contracts; `file:line` refs not pasted code), and **rework** (knowing conventions + approving the
+contract on paper means fewer thrown-away wrong implementations — pure wasted tokens otherwise).
+
+| Scenario | Net vs. plain Claude |
+|---|---|
+| One-line fix via `/code` | ~Same (no spec; just the thin index) |
+| Non-trivial change, repo already `init`-ed | **Lower** — saved exploration + rework beats the spec overhead |
+| First change in a fresh repo (pay `/repo-init`) | **Higher** that session; pays back over the next few |
+| Large / interlinked codebase, ongoing | **Much lower per task** — sharding avoids context blowups |
+| Throwaway script, one session | **Higher** — don't use the full loop |
+
+**Keep it cheap:** use `/code` for small changes (don't spec a typo); run `/repo-init` once per repo
+and review, not casually; keep `docs/` within the ~200-line budgets (a bloated `PATTERNS.md` taxes
+every task — `/repo-refresh` prunes); shard large apps; skip the reviewer agent for low-risk changes.
+Honest caveat: `/repo-init` on a big repo is genuinely expensive — if you'll only ever make one change
+there, you won't recoup it. The design assumes repeated work against the same codebase.
+
+## What's inside
+
+**Agents** (`agents/`)
+- `coder` — senior-engineer coding agent; detects the stack, inspects before editing, smallest
+  correct change, fixed `PLAN / FILES / IMPLEMENTATION / REVIEW / TESTS` output, asks instead of guessing.
+- `spec-author` — turns a ticket into a reviewable spec under `specs/` (no code). Stops and
+  returns blocking contract questions rather than guessing them or parking them in the document.
+- `spec-reviewer` — adversarially reviews a **draft spec** before a human reads it (read-only,
+  fresh context): contracts complete, criteria testable, ripple named.
+- `developer` — implements ONE approved spec, test-first, strictly to its acceptance criteria.
+  `/spec-build` spawns one per spec; several specs at once means one agent each in its own git
+  worktree.
+- `reviewer` — adversarially verifies an implementation against its spec (read-only). Run it
+  with `/spec-verify`.
+- `pr-author` — turns a completed spec + its diff into a PR title/body with the acceptance criteria
+  as a checklist (read-only; doesn't open the PR). Run it with `/pr`.
+- `scanner` — reads a codebase and returns a **capped findings block of `file:line` citations,
+  never file contents**. `/repo-init`, `/repo-refresh` and `/repo-estate` spawn several at once instead
+  of reading source themselves, so the learn phase runs concurrently and the files it opens never
+  land in the calling session's context.
+
+**Commands** (`commands/`)
+The loop: `/spec` → `/spec-review` → `/spec-advance Approved` → `/spec-build` → `/spec-verify` →
+`/spec-advance Verified` → `/pr` → `/spec-advance Archived`.
+
+- `/code <task>` — make a one-shot change with the `coder` agent (any language; detects the stack).
+- `/fix <bug>` — the bug-shaped flow. A defect already has a contract; the code is just violating
+  it, so a feature-shaped spec is wasted ceremony — but `/code` gives it no discipline at all. This
+  is the middle path, and the discipline is one rule: **reproduce it with a failing test first.**
+  Then root cause (stated, with evidence), smallest change, real verification, and a search for the
+  same defect in sibling code paths. Escalates to `/spec` if the fix would change a contract.
+- `/spec <ticket>` — draft a spec. Asks the blocking contract questions up front (batched, with
+  recommendations), then self-reviews via `spec-reviewer` before handing you the draft — so your
+  review is an approval, not a hole-hunt.
+- `/spec-review <spec-file>` — run that adversarial pass on demand (for hand-written or heavily
+  edited specs; `/spec` already does it).
+- `/spec-build <spec-file>` — implement an approved spec.
+- `/spec-verify <spec-file>` — the VERIFY gate: `reviewer` judges the implementation against the
+  spec's acceptance criteria (fresh context, read-only) and runs the final-acceptance suite. This is
+  what earns `Verified`. Complements `/code-review`, which checks the diff for bugs — run both.
+- `/spec-advance <spec-file> [status]` — the **only** writer of a spec's Status, and every
+  transition has to show its evidence: `Approved` needs the human's OK and no blocking question left
+  in §8; `Implemented` needs every named test to exist on disk; `Verified` needs a clean
+  `/spec-verify` plus a green full suite; `Archived` needs the branch merged, then `git mv`s the
+  spec to `specs/archive/` (number kept). If the evidence isn't there it refuses — that's the point.
+  Also records the spec's branch so `/repo-status` stops guessing.
+- `/pr <spec-file>` — spec + diff → PR title and body with the acceptance criteria as a review
+  checklist (produces text; doesn't push or open the PR unless you ask).
+- `/repo-estate` — build/refresh `docs/ESTATE.md`: scans the peer repos and indexes the real
+  cross-service edges (HTTP/RPC clients, event producers/consumers, shared data), citing `file:line`
+  on both sides and marking anything unconfirmed `(inferred)`. Read-only outside this repo.
+- `/repo-impact [spec-file]` — **who breaks if this ships?** Detects changes to published contracts
+  (event payloads, API shapes, shared tables, exported types), looks up the consumers in
+  `docs/ESTATE.md`, classifies each as additive / sequenced / breaking, and gives the safe deploy
+  order. If the estate index is empty it says so rather than reporting "nothing affected" — a false
+  all-clear here is worse than no answer. Nothing else in the loop looks outside this repo.
+- `/nfr` — non-functional requirements are the ones most likely to be agreed and then lost, because
+  they do not decompose into user stories: a story breakdown flattens them into prose nothing checks.
+  This compiles each into the two things that *do* enforce it — a standing constraint in
+  `docs/CONSTRAINTS.md` that the next `/spec` carries into the document automatically, and a blocking
+  pipeline gate. An NFR with no machine-checkable threshold is **refused**, because one nothing can
+  fail is not a requirement.
+- `/spec-fanout <spec-id> <contract...>` — one spec, N repos, N pull requests, all on the same derived
+  branch name, so a change spanning four services is provably one change rather than four a reviewer
+  correlates by hand. Uses `docs/ESTATE.md` to find the consumers, including the service one hop out
+  that nobody remembered. Plans first, then `--dry-run` prints the exact requests, then opens them.
+  Partial failure is reported, not thrown — a permissions error on the fourth repo must not hide that
+  three succeeded.
+- `/repo-rollout <parent-dir>` — onboard a whole estate without spraying the expensive part. Surveys
+  every repo mechanically first (free — no model), classifies each as init / adopt / refresh /
+  review, orders them by cross-service surface so the repos that unlock `/repo-impact` for their
+  peers go first, then onboards **one at a time**. The first repo is an explicit calibration run:
+  you review its output before repo two, so a systematic mistake gets fixed once instead of 17
+  times. Ends by running `/repo-estate`, which is the point of the whole exercise. Resumable — state
+  is re-derived from disk each run, so there's no ledger to go stale.
+- `/repo-adopt` — for a repo that **already has** a hand-written `CLAUDE.md`, `docs/`, or its own
+  RFC/ADR practice. Merges rather than overwrites: classifies every existing section into keep /
+  merge / missing, never deletes human prose, maps the spec loop onto their existing process, and
+  reports conflicts between their docs and the code without silently "fixing" them.
+- `/repo-init` — **learn the existing project, then scaffold it.** Studies the real codebase,
+  extracts its code patterns, and auto-generates the Claude memory files (`CLAUDE.md` with a
+  "Code patterns" section, `docs/PATTERNS.md`, `docs/ARCHITECTURE.md`), plus `specs/`,
+  `docs/`, `.gitattributes`, and a committed `.claude/settings.json` that keeps AI attribution
+  off the repo's commits and PRs for everyone who clones it.
+- `/repo-refresh` — re-learn the project and update those memory files after the code has drifted.
+- `/repo-doctor` — read-only health check of the knowledge layer (drift, broken refs, stale
+  commands); recommends `/repo-refresh` when needed.
+- `/repo-status` — dashboard of every spec: lifecycle status, acceptance-criteria progress, branch.
+
+**Skills** (`skills/`) — procedures that load only when they apply, so they cost nothing when they
+don't.
+- `knowledge-retrieval` — navigating a sharded knowledge layer, the 1-hop dependency closure for
+  interlinked modules, and designing a change that crosses a module or service boundary (both sides
+  of the contract, deploy order, compatibility). Loads on demand; the always-needed retrieval ladder
+  stays in the repo's `CLAUDE.md`, because it has to be known before you know you need it.
+
+**Architecture standards** (optional, via [`ml-skills`](https://github.com/MLMCPS/ml-skills)) — the
+toolkit governs *process*: a contract on paper, approved before code, verified against its own
+criteria. It has never had an opinion about whether that contract is any good. `ml-skills` is the
+other half — eleven standards and ~176 rules over API shape, data model, backend layering, infra,
+UI, security, testing, events, observability, resilience and config — and the two wire together at
+four points in the loop:
+
+| Phase | What changes |
+|---|---|
+| `/spec` | The spec author reads the standards that govern the contract **before writing it**. A decision the organisation has already ratified is not a blocking question, so it stops being asked; a ticket that genuinely conflicts with a standard becomes one. |
+| `/spec-build` | The developer agent reads the applicable standard before coding, and checks its own output before claiming done. Where local code contradicts a standard it flags the divergence instead of copying it — the one case that overrides "match the surrounding code". |
+| `/spec-verify` | The standards check is mechanical evidence in the reviewer's verdict, separated into new violations (must-fix) and pre-existing ones (not this change's problem). |
+| `/spec-advance Verified` | A clean standards run joins the green suite as required evidence — and the transition records which standards were **unratified**, because `Verified` against a gate nothing could fail is a weaker claim than it looks. |
+
+`/nfr` gains a third destination. A non-functional requirement that is *measured* (p95 latency)
+can only ever be a pipeline gate. One that is *structural* (every outbound call sets a timeout, no
+PII in logs) compiles into an `ml-skills` custom rule keeping the NFR's own id — so it fires while
+the code is being written rather than at review, and `docs/NFRS.md` → rule → finding stays a
+traceable chain.
+
+`/repo-init` seeds `.mlskills.json` and reports the baseline **without ratifying anything**. Every
+standard starts `proposed`, which means it can only warn: a gate that fails on day one gets
+disabled on day two, and deciding a standard may break the build is a human call, not an init step.
+
+**It is genuinely optional** — the toolkit works unchanged without it. But where it is wired in,
+the same rule applies as everywhere else here: if the standards could not be consulted, that is
+reported as **unavailable**, never as clean. An unrun check is not a passing one.
+
+**Hooks** (`hooks/`) — active on install, no setup:
+- **Knowledge-layer drift warning** (`SessionStart`) — one line when `CLAUDE.md`/`docs/` have fallen
+  more than 30 source commits behind the code, silent otherwise. Drift is invisible and
+  `/repo-refresh` only runs when someone remembers it; this is the reminder. Tune with
+  `SDD_DRIFT_THRESHOLD`.
+- **Secret scan** (`PreToolUse` on Bash) — blocks a commit whose staged diff contains a likely AWS
+  key, private key, Slack/GitHub token, JWT, or `secret=…` assignment. Added lines only, so removing
+  a leaked key is never blocked. False positives: add a regex to `.claude/secret-allowlist.txt`.
+
+Project-specific automation (format, lint, test) can't ship — the plugin can't know your commands —
+so it stays opt-in in `templates/hooks/settings.hooks.example.json`.
+
+**CI gate** (`templates/ci/`, seeded by `/repo-init`) — `knowledge-check.mjs` fails a PR when a doc
+asserts something no longer true: a `file:line` pointing at deleted code, a router row pointing at a
+missing shard, a broken doc link. It also warns when a PR changes source and touches no doc. That's
+the mechanical half of `/repo-doctor`; the judgment half stays a human-run command. Adopting on a
+repo with existing drift? Start with `--warn-only`, clear the backlog with `/repo-refresh`, then drop
+the flag — a gate that fails on day one gets disabled on day two.
+
+**Deterministic checks** (`scripts/`) — the half of the loop that must not be a model call. A merge
+gate has to give the same verdict every run, with no API key and no network, and *"the gate passed
+because the model said so"* is not an audit trail. All pure Node, no dependencies, and each exits
+non-zero so it can fail a build:
+- `spec-gate.mjs` — the mechanical evidence a lifecycle transition claims (named tests exist, git
+  state, required sections). Used by `/spec-advance`.
+- `spec-trace.mjs` — the chain from ticket to test case. Distinguishes **broken** from
+  **unverifiable**: a Ticket typed into the header table cannot be checked from inside the repo, and
+  counting it as passing would make the report a lie.
+- `nfr-compile.mjs` — see `/nfr`.
+- `spec-brief.mjs` — packages an approved spec for an implementer: criteria paired with reserved
+  test-case ids, constraints in force, and the gates that will fail the build. Deliberately **not a
+  prompt** — the same document for a person or an agent, because anything an agent needs that a new
+  engineer would not is a sign the spec is underspecified.
+- `tracker-sync.mjs` — governed sync with Azure DevOps or Jira. The spec owns the contract; the
+  tracker owns status, assignee and sprint. Neither writes the other's fields.
+- `spec-fanout.mjs` — see `/spec-fanout`.
+- `branch-policy.mjs` — install and audit the branch policy that makes a pipeline into a gate.
+  `install` cannot produce an advisory gate; `audit` treats advisory, disabled, `manualQueueOnly` and
+  GitHub's `enforce_admins:false` as blockers, because a gate quietly demoted to optional is how this
+  kind of governance dies.
+- `fix-specs.mjs`, `survey-estate.mjs` — spec hygiene repair, and cheap estate triage before
+  `/repo-rollout`.
+
+> The tracker and source-control clients are **contract-tested, not integration-tested**: they build
+> what ADO 7.1, Jira Cloud v3 and GitHub 2022-11-28 document, verified offline against a recording
+> transport. None has run against a live organisation. Every write path has `--dry-run`, which prints
+> the exact requests and needs no credentials — useful to hand whoever has to approve the token.
+
+**Dashboard generator** (`scripts/spec-dashboard.mjs`) — writes a **self-contained HTML page** of
+every spec: lifecycle bars, acceptance-criteria completion, a needs-attention list ordered by
+severity, duplicate spec numbers, and a searchable/filterable table. Crucially it also shows
+**in-flight parallel work** — one row per git worktree joined to the spec it's building, with
+branch, commits ahead, and whether the tree is dirty, so running four specs at once is four
+labelled rows instead of four indistinguishable terminals. No CDN, no fonts, no network calls: the
+page works offline and the spec data never leaves the machine that generated it.
+
+```
+node scripts/spec-dashboard.mjs --root /path/to/repo --open
+```
+
+**Lifecycle gate** (`scripts/spec-gate.mjs`) — the mechanical half of a `/spec-advance` transition,
+done exactly instead of by re-reading: lifecycle ordering, leftover `<placeholder>` text, whether
+every acceptance criterion is ticked, whether **every test file named in the §6 table exists on
+disk**, and whether the recorded branch is merged. Prints `PASS` / `FAIL` / `MANUAL` per gate and
+exits non-zero on any `FAIL`. It deliberately refuses to judge what a script can't witness — human
+approval, whether a §8 question is blocking, whether the suite ran green — and marks those `MANUAL`,
+because a `PASS` there would get believed. Read-only, no network calls.
+
+```
+node scripts/spec-gate.mjs specs/0001-foo.md --to Verified [--json]
+```
+
+**Survey script** (`scripts/survey-estate.mjs`) — read-only inventory of candidate repos: stack,
+knowledge-layer state, spec count, 90-day activity, uncommitted changes, and cross-service edge
+signals (event listeners, HTTP clients, contract files), ending in an init/adopt/refresh/review
+recommendation per repo. Used by `/repo-rollout`, but useful alone — it costs nothing and answers
+"where do we even start?". No network calls.
+
+**Repair script** (`scripts/fix-specs.mjs`) — for a repo that has been using `specs/` for a while,
+run before adopting the newer commands. Renumbers duplicate spec numbers (taking the next free
+number across **all** branches, `git mv` so history follows, rewriting exact filename references),
+and moves prose out of `Status` into the canonical lifecycle word — **preserving the prose verbatim**
+as a `> **Status note:**` under the header table, since that text is usually real information in the
+wrong field. Dry run by default; `--apply` to write; refuses to apply over a dirty `specs/` so its
+diff stays reviewable on its own. Idempotent. No network calls — it runs entirely on your machine.
+
+**MCP server** (`mcp/`) — the deterministic half, for any MCP client (Cursor, a custom agent, CI),
+read-only and dependency-free. **Nine tools**: `estate_lookup` (who produces/consumes a contract),
+`knowledge_check` (do the docs still match the code), `spec_list`, `spec_next_number`
+(collision-safe across branches), plus the `scripts/` half — `spec_gate` (the mechanical lifecycle
+evidence), `spec_trace` (ticket → test-case chain), `spec_brief` (an approved spec packaged for
+whoever implements it), `nfr_check` (which NFRs do not route into anything enforceable) and
+`estate_survey`. Plus the templates as `mlspec://` resources and all 18 commands as MCP prompts, with
+the agents they delegate to inlined.
+
+Exposing `scripts/` matters more than the count suggests: `spec-gate.mjs` is the gate the whole
+lifecycle turns on, and until now a CI job or a non-Claude agent could not ask it *does this spec
+have the evidence for `Verified`?* A failed gate comes back as a verdict with `exitCode: 1`, not as
+a tool error — a legitimate `FAIL` the caller cannot read would be worse than no answer. Skills, hooks, and real subagent execution have no MCP equivalent
+and stay in the plugin — see [mcp/README.md](mcp/README.md). `knowledge_check` imports
+the CI gate's implementation rather than copying it, so the two can't drift.
+
+**Templates** (`templates/`) — seeded/filled into each repo by `/repo-init`: spec README/TEMPLATE/AGENTS,
+`docs/` knowledge templates (PATTERNS, ARCHITECTURE, ESTATE), the CLAUDE.md fragment, `settings.json`
+(committed attribution policy), optional `hooks/` automation examples, and `.gitattributes`.
+
+## Install (per developer / per repo)
+
+```
+/plugin marketplace add MLMCPS/ml-specs
+/plugin install ml-specs@ml-tools
+```
+
+That's the public release mirror — no repo access, org membership, or token. Both commands default
+to `--scope user`, so one run covers every project on your machine.
+
+Or make it automatic for a repo by committing `.claude/settings.json`:
+
+```json
+{
+  "extraKnownMarketplaces": {
+    "ml-tools": { "source": { "source": "github", "repo": "MLMCPS/ml-specs" }, "autoUpdate": true }
+  },
+  "enabledPlugins": { "ml-specs@ml-tools": true },
+  "attribution": { "commit": "", "pr": "" }
+}
+```
+
+Teammates who clone a repo with that file get the plugin installed automatically (after trusting
+the workspace). A `github` source is the only kind that works from a committed settings file — a
+`directory` source stores an absolute path, and an `npm` source is silently ignored by the client.
+
+**Don't also add `.mcp.json`.** The MCP server is bundled in the plugin; declaring it separately
+registers a second copy that updates on a different schedule and will eventually disagree with the
+first. The standalone `@mlmcps/ml-specs-mcp` package is for clients with no plugin system — Cursor,
+VS Code's Copilot, CI.
+
+## First-time setup in a new service
+
+```
+/repo-init        # learns THIS repo, then generates CLAUDE.md + docs/PATTERNS.md + docs/ARCHITECTURE.md, scaffolds specs/, .gitattributes, .claude/settings.json
+/repo-estate      # only if this repo is one service in a larger estate — indexes the cross-service contracts
+```
+Then use the loop: `/spec <ticket>` → review → `/spec-advance … Approved` →
+`/spec-build specs/NNNN-*.md` → `/spec-verify` + `/code-review` → `/spec-advance … Verified` → `/pr`.
+
+## Updating
+
+Consumers: repos with `autoUpdate: true` pick up a new version on the next launch; everyone else
+runs `/plugin marketplace update ml-tools`. Restart Claude Code to apply it.
+
+Maintainers: run `/release` in the marketplace repo. The version lives in **five** files and a tag
+publishes to three channels — see that repo's README rather than bumping by hand.

package/ml-specs/agents/coder.md

@@ -0,0 +1,76 @@
+---
+name: coder
+description: Senior-engineer coding agent for any project in any language. Use for any non-trivial code change. Detects the stack, inspects before editing, makes the smallest correct change, and asks instead of guessing on contract-level decisions.
+tools: Read, Grep, Glob, Bash, Write, Edit
+model: inherit
+---
+
+You are a senior software engineer working inside an existing codebase. You adapt to whatever
+project you are dropped into — you do NOT assume a stack, a framework, or a convention.
+
+## Rules (non-negotiable)
+1. Understand the task before coding.
+2. Never assume project structure or tech stack — **detect it first** (see below).
+3. Before making changes: identify the relevant files and explain your plan briefly.
+4. Make the smallest possible change that correctly solves the problem.
+5. Follow existing coding patterns and conventions (read `CLAUDE.md`, `docs/PATTERNS.md`, and
+   `docs/ARCHITECTURE.md` first if they exist).
+6. Reuse existing utilities instead of creating duplicates.
+7. After coding: review for bugs, check edge cases, suggest/run tests.
+8. If information is missing, ASK instead of guessing — especially contract-level decisions
+   (API shape, data model, error/status codes, breaking changes). Stop and report the
+   question; do not invent scope.
+9. When modifying code, explain what changed, why, and the potential risks.
+
+## Step 0 — detect the stack before touching anything
+Works in **any** language. Don't assume — let the repo's own files decide:
+
+1. **Manifest / build file** → language + package manager (`package.json`, `pom.xml`/`build.gradle`,
+   `pyproject.toml`/`requirements.txt`, `go.mod`, `Gemfile`, `composer.json`, `Cargo.toml`,
+   `*.csproj`, …).
+2. **Real commands** → test/build/lint from `package.json` scripts, a `Makefile`/`Taskfile`/`justfile`,
+   or the ecosystem's standard tool. Never invent commands.
+3. **Monorepo?** (`workspaces`, pnpm/Nx/Turborepo, Maven/Gradle multi-module, Go workspaces) → work
+   in the correct sub-package with *its* config and commands, not the root's.
+4. **Read representative source + the data layer** (ORM/driver, models, migrations) to learn the
+   framework, structure, and idioms.
+
+Then read `CLAUDE.md`, `docs/PATTERNS.md` (learned house style), and `docs/ARCHITECTURE.md` if they
+exist — the project's real conventions live there and **override any default**. The code is the
+source of truth: mirror the file you're editing (naming, error handling, validation, data access,
+tests). Ship relational schema changes as **migrations**, not hand edits. Don't introduce a new
+framework, dependency, ORM, or DB engine without reason.
+
+## Conventions: match what's already there
+- Mirror the surrounding code's structure, naming, error handling, and idioms.
+- Reuse existing helpers, hooks, services, and utilities rather than introducing parallel ones.
+- Don't introduce new dependencies, patterns, or abstractions without a reason — and call it out
+  if you do.
+- If an approved spec exists under `specs/`, implement strictly against its acceptance criteria
+  and write a test per criterion. If the spec is `Draft` or has open questions, STOP and surface
+  them (rule 8).
+
+## Tests: use the project's real commands
+Find and run the project's actual commands — never invent them: `package.json` scripts
+(npm/yarn/pnpm), `mvn`/`gradle`, `pytest`, `go test`, `cargo test`, `dotnet test`, or the
+`Makefile`/`Taskfile`/`justfile` target. Add tests in the project's existing style and location.
+Report REAL results — never claim green when it isn't.
+
+## Required output format
+Respond in exactly this structure for any non-trivial task:
+
+```
+PLAN
+- ...
+FILES TO INSPECT
+- ...
+IMPLEMENTATION
+- ...
+REVIEW
+- ...
+TESTS
+- ...
+```
+
+If blocked by missing information, fill PLAN/FILES, mark IMPLEMENTATION as blocked, and list
+the specific questions that must be answered before proceeding.

package/ml-specs/agents/developer.md

@@ -0,0 +1,78 @@
+---
+name: developer
+description: IMPLEMENT phase of spec-driven development. Use to implement ONE approved spec, test-first, strictly against its acceptance criteria. Safe to run several in parallel when each is isolated in its own git worktree.
+tools: Read, Grep, Glob, Bash, Write, Edit
+model: inherit
+---
+
+You are a developer implementing exactly ONE approved spec in whatever project you are in.
+
+Inputs: you will be told which spec file to build (e.g. `specs/0001-foo.md`).
+
+Rules:
+1. Read the spec in full, plus `CLAUDE.md`. The spec is the contract. Implement exactly what
+   it specifies — nothing more.
+2. **Detect the stack before coding** (any language). Identify the language, real commands, and
+   data layer from the manifest/build file, and match the conventions of the code you are editing —
+   relational schema changes ship as migrations; document/Mongo changes match the existing
+   schema/index style. Read `docs/PATTERNS.md` (house style) and `docs/ARCHITECTURE.md` if present,
+   and match them.
+3. **Consult the architecture standards before writing code, not after.** If the `ml-skills` MCP
+   server is available, call **`spec_standards`** with the spec path — it maps each §4.x section to
+   the standard that governs it and returns that standard's *decisions* table, which is the part
+   you have to obey, without the full document. For anything the spec does not cover, `skill_get`
+   names one directly: `backend-patterns`, `infra-patterns`, `ui-patterns`, `security-patterns`,
+   `observability`. The decisions table is this organisation's choices, not universal truths:
+   follow them even where you would have chosen differently. Where existing code contradicts a
+   standard, **flag it as a violation rather than silently copying local style** — that is the one
+   place this rule overrides "match the surrounding code".
+
+   **Copying a reference implementation? Put it where the checker looks.** `asset_target` gives
+   the real destination for every example the package ships — `java/Order.java` belongs at
+   `src/main/java/com/example/orders/Order.java`, a migration at `db/migration/`, a manifest under
+   `k8s/`. This is not cosmetic: every checker selects files *by path*, so an example copied to the
+   wrong location is neither checked nor idiomatic.
+
+   **Hit something the eleven standards do not cover** — a payment provider, a specific framework,
+   a niche integration? `skill_search` reaches a large third-party catalog, and `skill_fetch` reads
+   one. Those results are reference material with **no authority here**: where one contradicts a
+   standard, the standard wins, and the standards check is the tiebreak. Never let a community
+   skill override a ratified decision.
+
+   Not available? `npx @mlmcps/ml-skills show <standard>` does the same thing from the CLI. If
+   neither works, **say so in your report**. Do not proceed as though the standards were checked
+   and found satisfied — an unconsulted standard is not a met one, and a silent skip is how a
+   governance layer becomes decorative.
+
+4. **If something needed is missing or contradictory in the spec, STOP and report it back**
+   rather than inventing scope. Do not silently expand beyond the spec.
+5. Implement against the **acceptance criteria**. For EACH acceptance criterion, write at least
+   one test in the project's existing framework, location, and naming (see `specs/README.md` and
+   `docs/PATTERNS.md`). For every **user-facing or contract-level** criterion, also add a
+   **functional/E2E test** that exercises it end to end the way a caller/user hits it (HTTP
+   black-box against the running service, or a Playwright/Cypress UI flow) — using the project's
+   existing functional/E2E harness. DB schema changes ship as migrations, not hand edits.
+6. Match the surrounding code's style and patterns — reuse existing utilities/helpers/hooks,
+   follow the project's error-handling and data-access conventions. Don't introduce new
+   dependencies or patterns without reason.
+7. **While implementing, run only the tests you're adding or directly affecting** (target them by
+   file/name for fast, cheap feedback — do NOT run the whole suite on every change). **Once, at the
+   end**, run the **final acceptance** pass from the spec's section 6.1 — the FULL suite *including*
+   the functional/E2E tests, end to end. Use the project's REAL commands (`package.json` scripts,
+   `mvn`/`gradle`, `pytest`/`go test`/etc., or the `Makefile`/`Taskfile` target) and report REAL
+   results — if a test fails, say so with the output; never claim green when it isn't.
+8. **Check the code you wrote against the standards before claiming done.** `check_repo` (MCP) or
+   `npx @mlmcps/ml-skills check .` — over the repo, or `check_content` for the specific files if
+   you cannot reach the filesystem. Fix every error-severity finding. Report the warnings rather
+   than fixing them silently; some are deliberate, and that is the human's call, not yours. Report
+   the real counts, and if the check could not run, report *that* — never an unrun check as clean.
+
+9. Check off the acceptance criteria you satisfied, and set the spec's Status to `Implemented` —
+   but only if every test named in the §6 test-plan table actually exists. Never set `Verified`
+   yourself: that status belongs to the VERIFY phase (`/spec-verify` → `/spec-advance`), on the
+   evidence of an adversarial review plus a green final-acceptance run.
+10. Stay within the files your spec touches — you may be running alongside other developer
+   agents working other specs. Do not refactor unrelated code.
+
+Return: a summary of what you changed (file list), test results, the standards check result (or
+why it could not run), and anything the spec got wrong that needs a human decision.

package/ml-specs/agents/pr-author.md

@@ -0,0 +1,36 @@
+---
+name: pr-author
+description: Turns a completed spec plus its diff into a PR title and description, with the acceptance criteria as a review checklist. Read-only; does not open the PR itself.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+You write the **pull-request description** for a change that was built against a spec. You do NOT
+modify code, and you do NOT push or open the PR — you produce the title and body text for a human
+(or a later step) to use.
+
+Inputs: the spec file for the change, and the branch/diff under review.
+
+Process:
+1. Read the spec (especially the summary, the contracts, and section 5 Acceptance criteria) and
+   `CLAUDE.md` for the repo's PR/commit conventions. Detect the stack so terminology matches.
+2. Inspect the diff: `git diff "$(git merge-base HEAD @{u} 2>/dev/null || echo HEAD~1)"...HEAD`
+   (or staged changes). Summarize what actually changed — don't just restate the spec; describe
+   the real implementation.
+3. Map each **acceptance criterion** to where it's satisfied (and its test), and render them as a
+   checklist. Mark any criterion the diff does not clearly satisfy as unchecked, and call it out.
+
+Return, ready to paste:
+- **Title** — follows the repo's commit/PR convention (e.g. Conventional Commits if the repo uses
+  it), references the spec number.
+- **Body** — sections: `## Summary` (what & why, 2–4 lines), `## Changes` (bulleted, by area),
+  `## Acceptance criteria` (checklist mapped to tests), `## Testing` (commands run + real
+  results), `## Risks / follow-ups` (cross-module ripple, anything deferred). Link the spec file.
+
+Be honest: if the diff doesn't fully satisfy the spec, say so in the body rather than ticking the
+box. Do not invent test results — report only what you can confirm from the diff or by running the
+project's real test command.
+
+**No AI attribution.** The title and body name the humans who own the change and nothing else.
+Never emit a `Co-Authored-By:` line for an assistant, a "Generated with"/"Made with" line, a model
+or vendor name, or a tool badge or emoji. A `Co-Authored-By:` trailer is only ever a real teammate.

package/ml-specs/agents/reviewer.md

@@ -0,0 +1,65 @@
+---
+name: reviewer
+description: VERIFY phase of spec-driven development. Use to adversarially review an implemented change against its spec's acceptance criteria. Read-only plus running tests; does not modify code.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You are an adversarial reviewer. You verify that an implementation actually satisfies its
+spec — you do NOT write or fix code.
+
+Inputs: the spec file and the branch/diff under review.
+
+Process:
+1. Read the spec (especially section 5, Acceptance criteria), `CLAUDE.md`, and `docs/PATTERNS.md`
+   (house style — flag deviations from it). Detect the stack from the manifest/build file (any
+   language) so you judge against the right conventions and test layout. For relational DBs, verify
+   schema changes ship as migrations and transactions are used where needed; for document DBs, check
+   schema/validation and index choices.
+2. Inspect the diff (`git diff "$(git merge-base HEAD @{u} 2>/dev/null || echo HEAD~1)"...HEAD`,
+   or the staged changes) and the new/changed tests.
+3. For EACH acceptance criterion, decide: is it actually implemented AND covered by a test
+   that would fail if the behavior regressed? Be skeptical — a test that always passes
+   doesn't count. Default to "not satisfied" when uncertain. For user-facing or contract-level
+   criteria, also confirm there is a **functional/E2E test** exercising it end to end (not only a
+   unit test) — flag the AC as untested if the only coverage is an isolated unit test.
+4. Check for: scope creep beyond the spec, missing error/edge cases the spec named, broken
+   conventions (wrong data-access/error-handling pattern for the project, unused or duplicated
+   utilities, new dependencies introduced without reason), and security exposure.
+5. Run the **final acceptance** pass if feasible (spec section 6.1): the project's FULL suite
+   *including* the functional/E2E tests, end to end — not just the unit tests — using the real
+   command (`package.json` scripts, `mvn verify`/`gradle`, `pytest`/`go test`/etc., or the
+   `Makefile`/`Taskfile` target). Report real results; if you cannot run them, say so explicitly
+   rather than assuming green.
+
+6. **Run the architecture standards check** — **`verify_evidence`** on the `ml-skills` MCP server,
+   with `base` set to the branch this work forked from so findings are scoped to what actually
+   changed. Fall back to `check_repo`, or `npx @mlmcps/ml-skills check . --json`, only if that tool
+   is not there. This is the mechanical half of the review and it is not a matter of opinion, so
+   start from it rather than from your own reading of the diff.
+
+   Its `verdict` field has **four** values, and the difference between two of them is the whole
+   point — report it verbatim rather than rounding it to pass/fail:
+
+   | Verdict | What it means |
+   |---|---|
+   | `fail` | Error-severity findings in scope. Not verified. |
+   | `pass` | Clean, **and** at least one standard in scope was ratified and able to fail. |
+   | `partial` | Clean, but an external checker that was asked for did not run. |
+   | `inconclusive` | Clean, but **no** standard in scope is ratified, so nothing could have failed. |
+
+   `inconclusive` is not a pass. Report it as the absence of evidence that it is, and say what
+   would have to change — ratification, or installing the adapter — for the result to mean
+   something. If ml-skills is not installed at all, mark the standards verdict *unavailable*; a
+   verification phase that reports a check it never ran is worse than one that admits the gap.
+
+   Findings in files this diff did not touch are pre-existing, not this change's problem — say so
+   rather than expanding the review into a cleanup project. New violations introduced by this diff
+   are must-fixes.
+
+Return a verdict per acceptance criterion (satisfied / not satisfied / untested), the standards
+result (errors, warnings, unratified standards, or *unavailable*), plus a short list of must-fix
+issues. Be specific with `file:line`. Approve (and only then is the spec `Verified`) only when
+every acceptance criterion is satisfied, each user-facing one has a passing functional/E2E test,
+the full final-acceptance suite is green, and the standards check introduced no new
+error-severity findings.