@mlmcps/ml-specs 1.0.0

package/ml-specs/templates/docs/ARCHITECTURE.template.md

@@ -0,0 +1,110 @@
+# <project name> — architecture summary
+
+> Auto-maintainable summary the coding agent reads **first** to orient before searching.
+> Regenerate when structure/endpoints/data layer change (see "Keeping this fresh" at the bottom).
+> Source of truth is the code; if this disagrees with the code, the code wins — fix this file.
+>
+> This is a **stack-neutral skeleton**. Keep the sections that apply to THIS project's stack
+> (Java/Spring, React, Node/Express, NestJS, or any other) and delete the rest. Fill every kept
+> section with real `file:line` references — do not leave placeholders.
+>
+> **Token budget: keep this under ~200 lines.** It's a *map*, not the territory — terse tables and
+> `file:line` pointers, not prose or pasted code. If it grows past the budget, split per-context /
+> per-package or push detail down into the code (which the agent greps on demand).
+>
+> **Large application? Shard it (the key scaling move).** Do NOT grow one giant file. Keep THIS
+> file as a tiny **router**: the "What it is" blurb + the Structure table where each row links to a
+> per-module shard `docs/architecture/<module>.md` (each its own ≤~150-line map). The agent reads
+> this router (cheap), then loads only the ONE shard for the module a task touches. Same idea for
+> patterns: a per-module `docs/patterns/<module>.md` when conventions differ across modules.
+> See "Large-codebase layout" at the bottom.
+
+## What it is
+<1–3 sentences: what this app/service does, the stack (language, framework, build tool), and
+the database engine. Rough size (file/LOC count) helps. If it's one of several services, say so
+and link `docs/ESTATE.md`.>
+
+## Structure (where to look by feature)
+<How the code is organized. Pick the shape that matches the stack:>
+- **Java/Spring:** bounded contexts / packages — `controller → service → domain → repository`,
+  plus `events/*` for messaging. Table of contexts with base path + one-liner.
+- **Node (Express/NestJS):** modules/routers → controllers → services/providers → data layer;
+  middleware or guards/interceptors/pipes. Table of modules with route prefix + one-liner.
+- **React:** routes/pages → feature components → shared components/hooks → API/data layer; where
+  state lives. Table of routes/features with one-liner.
+
+| Area / module / route | Path | One-liner |
+|-----------------------|------|-----------|
+| | | |
+
+## Data & persistence (the #1 gotcha)
+<The database and how the code talks to it. Be specific — this is where bugs hide.>
+- **Engine:** MySQL / PostgreSQL / MongoDB (+ any cache like Redis, object store like S3).
+- **Access layer:**
+  - Relational: ORM (Sequelize/Prisma/TypeORM, or Spring Data JPA) — where models/entities and
+    **migrations** live; transaction style; dialect-specific bits.
+  - MongoDB: Mongoose/Spring Data Mongo schemas, validation, indexes; reactive vs blocking (Java).
+- **Migrations:** how schema changes ship (e.g. `sequelize-cli db:migrate`, Prisma migrate, Flyway).
+
+## Events / async / side-effects
+<Queues, topics, jobs, webhooks, cache invalidation, email. Producer/consumer + payload + failure
+handling. Omit if the app has none.>
+
+## External / cross-service calls
+| Client / proxy | Target | Purpose |
+|----------------|--------|---------|
+| | | |
+<HTTP clients, Feign proxies, third-party SDKs. Note error/timeout handling. Omit if none.>
+
+## Cross-cutting
+- **Errors:** how errors are represented and surfaced (global handler/middleware/filter; error
+  types). Don't invent ad-hoc error shapes.
+- **Auth:** in-app (JWT/passport/guards) or delegated to a gateway? Say which.
+- **Config:** env vars / `.env` / config server / profiles.
+- **Quality gates:** lint/format/typecheck and test commands (see CLAUDE.md).
+
+## Large-codebase layout (sharded — fill the Structure table above with these links)
+For a big app, this file is just the router; the detail lives in per-module shards loaded on demand:
+```
+docs/
+  ARCHITECTURE.md            # THIS router: blurb + Structure table + the contract index below
+  architecture/
+    <module-a>.md            # ≤~150 lines: structure, data, events, calls + a "Depends on/Used by" header
+    <module-b>.md
+  patterns/                  # only if conventions differ per module
+    <module-a>.md
+```
+The agent's path: read `ARCHITECTURE.md` (router) → open the ONE shard for the module the task
+touches → grep within that module for exact lines. It never loads modules it isn't working on.
+
+### When modules are interlinked (edges, not just nodes)
+Sharding by module only works if you also capture the **contracts between modules** — otherwise a
+change that ripples across modules misses the other side. So:
+
+- **Every shard starts with a `## Depends on / Used by` header** listing its edges — the modules it
+  calls and is called by, each as a one-line contract pointer (`event/API/shared type → file:line`).
+  This is the cheap, always-small part; it's what makes the graph navigable.
+- **Module contract index (below)** is the join table: the shared contracts (events, shared
+  DTOs/types, shared DB tables, internal APIs) and which modules produce/consume each.
+- **Load the dependency closure, bounded:** for a task on module X, load X's full shard **plus only
+  the `Depends on / Used by` + relevant contract section of its direct neighbors** — not the
+  neighbors' full shards. That's 1-hop: enough to honor the contract, still bounded.
+- **If "everything depends on everything"** that's coupling worth surfacing, not hiding. Keep a
+  single always-loaded **`docs/architecture/_core.md`** for the truly shared contracts, and let the
+  **spec** own the cross-module contract explicitly (template §4.1/4.3/4.4). Tightly-coupled specs
+  must be **sequenced, not parallelized** (see `specs/AGENTS.md`).
+
+## Module contract index (the join table — keep in the router)
+> The shared edges, so a change designs against both sides. One row per shared contract.
+
+| Contract (event / API / shared type / table) | Produced by | Consumed by | Defined at |
+|-----------------------------------------------|-------------|-------------|------------|
+| | | | `file:line` |
+
+## Keeping this fresh
+Regenerate (or `/repo-refresh`) after changes to routes/endpoints/controllers, the data model or
+migrations, event listeners, or external clients. Refresh only the shard(s) that changed — not the
+whole set. Use the project's own search (the right grep/glob for the stack), e.g. controllers/route
+definitions, `@SqsListener`/queue consumers, ORM model & migration dirs, external-client/proxy
+definitions. This file (+ `docs/ESTATE.md` if part of an estate) is the retrieval index; a stale
+summary is worse than none.

package/ml-specs/templates/docs/ESTATE.template.md

@@ -0,0 +1,55 @@
+# <estate name> — service & contract index
+
+> Estate-level retrieval index for the coding agent. When a change crosses a service boundary
+> (an event, an HTTP/RPC call, a shared table), this is where the agent learns **the other side of
+> the contract** without cloning and grepping every repo. Generated and refreshed by `/repo-estate`.
+>
+> Keep it under ~200 lines — it's an index, not documentation. One copy per service repo, kept in
+> sync (or hosted centrally and symlinked). Mark anything not confirmed against real code
+> `(inferred)` so the agent re-checks it instead of trusting it.
+
+## Service registry
+
+One row per service in the estate. `Summary doc` points at that repo's own `docs/ARCHITECTURE.md`
+(the deep detail lives there, not here). Use `_TBD_` for peers not onboarded yet — an honest gap is
+better than a guess.
+
+| Service | Owns | Stack | Summary doc |
+|---------|------|-------|-------------|
+| <this-service> | <the domain nouns it is the source of truth for> | <language / framework / datastore> | `<this-service>/docs/ARCHITECTURE.md` |
+| <peer-service> | <domain> | <stack, or `_TBD_`> | `_TBD_` |
+
+## Cross-service contract index (who calls / publishes / consumes what)
+
+The point of this file. Every row is an **edge** between two services — the agent reads it to find
+the peer's side before designing a change.
+
+### Synchronous (HTTP / RPC / gRPC / Feign)
+
+| Caller | Callee | Via | What | Evidence |
+|--------|--------|-----|------|----------|
+| <service> | <peer> | <client class / module name> | <what it asks for> | `path/to/Client.ext:42` |
+
+### Asynchronous (events / queues / topics)
+
+| Event / queue / topic | Producer | Consumer | Notes | Evidence |
+|-----------------------|----------|----------|-------|----------|
+| `<event-name>` | <service> | <service> (`<listener class>`) | <payload gist, ordering/idempotency> | `path/to/Listener.ext:17` |
+
+> Queue/topic names often resolve from config rather than literals — note where
+> (`<config key or config server path>`). Update this table whenever a listener or a published
+> topic is added.
+
+### Shared data & packages (optional — delete if none)
+
+| Shared thing | Owner | Used by | Notes |
+|--------------|-------|---------|-------|
+| <table / collection / shared library / published type> | <service> | <services> | <coupling risk, migration order> |
+
+## How to use this for retrieval
+
+1. Read this repo's own `docs/ARCHITECTURE.md` first (in-repo orientation).
+2. Only if the task touches an event, a cross-service call, or shared data: find the edge in the
+   contract index above, then open the peer's summary doc — design the change against **both**
+   sides of the contract, and note the deploy order in the spec's §7 Rollout.
+3. Only then do agentic search (`Explore` / grep) for the exact lines.

package/ml-specs/templates/docs/PATTERNS.template.md

@@ -0,0 +1,80 @@
+# <project name> — code patterns & conventions
+
+> Learned from the existing codebase by `/repo-init`. This is the agent's "house style" memory:
+> how THIS project actually writes code, so new code matches what's already there. Every pattern
+> below must cite a real example (`path/to/File.ext:line`). The code is the source of truth — if a
+> pattern here drifts from reality, fix this file.
+>
+> Keep only the rows that apply to this stack; delete the rest. Be concrete, not generic
+> ("controllers return `Mono<ResponseEntity<Dto>>` and never throw raw" beats "uses MVC").
+>
+> **Token budget: keep this under ~200 lines.** This loads into context whenever code is written.
+> Cite `file:line` examples — do NOT paste code blocks. One bullet per pattern. In a monorepo,
+> give each package its own short section (or its own `PATTERNS.md`) rather than one fat file.
+>
+> **Mark confidence.** A pattern with 3+ consistent examples is the rule — state it plainly. A
+> pattern seen once or guessed, prefix `(inferred)` so the agent re-checks it against the code
+> before relying on it. A wrong pattern stated as law is worse than an omission. Never invent a
+> convention to fill a section — delete the section instead.
+
+## Stack snapshot
+- **Language / framework:** <e.g. TypeScript + NestJS 10 / Java 17 + Spring Boot 3 / React 18 + Vite>
+- **Build / package manager:** <Maven · Gradle · npm · yarn · pnpm> (from lockfile)
+- **Database / ORM:** <PostgreSQL + Prisma · MySQL + Sequelize · MongoDB + Mongoose · Spring Data>
+- **Test stack:** <JUnit · Jest · Vitest · Supertest · @nestjs/testing · Playwright>
+- **Lint / format / typecheck:** <ESLint + Prettier · `tsc --noEmit` · Checkstyle/Spotless>
+
+## Directory layout
+<The real tree the agent should mirror when adding files. One line per significant dir + what lives there.>
+```
+src/
+  ...        # <what goes here>
+```
+
+## Naming conventions
+- **Files:** <e.g. `kebab-case.ts`, one component per file; `*.controller.ts` / `*.service.ts`>
+- **Types/classes/components:** <`PascalCase`; React components `PascalCase.tsx`>
+- **Functions/vars:** <`camelCase`>; **constants:** <`SCREAMING_SNAKE`>
+- **Tests:** <`*.spec.ts` next to source / `*Test.java` / `__tests__/`>
+- Example: `path/File.ext:line`
+
+## How a feature is structured (the layered flow)
+<Trace one real feature end to end so the agent can copy the shape. e.g.>
+- Entry: <route/controller> — `path:line`
+- Business logic: <service/provider> — `path:line`
+- Data access: <repository/model/ORM> — `path:line`
+- Input/output shape: <DTO/schema/validation> — `path:line`
+
+## Data access & migrations
+- How models/entities are defined — `path:line`
+- How queries/transactions are written (ORM calls, not raw SQL unless shown) — `path:line`
+- How schema changes ship (migration dir + command, e.g. `sequelize-cli db:migrate`) — `path:line`
+
+## API / interface contracts
+- Request validation: <Zod / class-validator / Joi / Bean Validation> — `path:line`
+- Response shape & serialization (DTOs, never leak entities) — `path:line`
+- Status codes / pagination / common envelope, if any — `path:line`
+
+## Error handling
+- Error types and where they're thrown — `path:line`
+- Central handler/middleware/filter that maps them to responses — `path:line`
+- Rule: <e.g. "throw typed errors, never build ad-hoc error bodies in controllers">
+
+## Validation, config & secrets
+- Config/env access pattern (`.env`, config service, `@ConfigService`) — `path:line`
+- Never hard-code secrets; how the project reads them — `path:line`
+
+## Logging & observability
+- Logger used and how it's invoked — `path:line`
+
+## Testing patterns
+- Unit test shape (arrange/act/assert, mocking style) — `path:line`
+- Integration test shape (test DB, fixtures, Supertest/`@nestjs/testing`) — `path:line`
+- Functional/E2E shape (HTTP black-box against the running app; Playwright/Cypress UI flows;
+  how the app/DB is started for the run) — `path:line`
+- Test command(s): unit/integration `<npm test, mvn test, …>`; functional/E2E
+  `<npm run test:e2e, mvn verify, npx playwright test, …>`; full final-acceptance run
+  `<the command that runs everything end to end>`
+
+## Don'ts (project-specific anti-patterns observed/avoided)
+- <e.g. "no `any` — strict TS", "no raw SQL", "no new `.block()` calls", "no direct entity returns">

package/ml-specs/templates/gitattributes

@@ -0,0 +1,18 @@
+# Normalize line endings: store LF in the repo, check out LF on all platforms.
+# Prevents the whole-repo CRLF/LF "phantom diff" churn.
+* text=auto eol=lf
+
+# Keep Windows scripts as CRLF
+*.bat text eol=crlf
+*.cmd text eol=crlf
+
+# Treat known binaries as binary (no EOL conversion, no diff)
+*.jar binary
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.pdf binary
+*.zip binary
+*.gz binary

package/ml-specs/templates/hooks/settings.hooks.example.json

@@ -0,0 +1,32 @@
+{
+  "//": "OPTIONAL example hooks — the PROJECT-SPECIFIC ones the plugin cannot ship for you,",
+  "//1": "because it can't know your format/lint/test commands. Copy what you want into this",
+  "//2": "repo's .claude/settings.json and REPLACE the commands with the real ones. Hooks run",
+  "//3": "automatically, so keep them fast and non-destructive. Delete this file after wiring up.",
+
+  "//4": "ALREADY SHIPPED BY THE PLUGIN — do not copy these, they are active on install:",
+  "//5": "  SessionStart  → knowledge-layer drift warning (silent unless drifted)",
+  "//6": "  PreToolUse    → staged-diff secret scan (blocks the commit; allowlist at",
+  "//7": "                  .claude/secret-allowlist.txt). See ml-specs/hooks/.",
+
+  "hooks": {
+    "//PostToolUse": "Auto-format / lint the file just edited. Pick the matcher + command for your stack.",
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "//note": "JS/TS example — run prettier on changed files. Swap for your formatter (spotlessApply, black, gofmt…).",
+        "hooks": [
+          { "type": "command", "command": "npx --no-install prettier --write \"$CLAUDE_FILE_PATHS\" 2>/dev/null || true" }
+        ]
+      }
+    ],
+    "//Stop": "Remind to run the quality gates before finishing. Replace with the real test command.",
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "echo 'Reminder: run the project test + lint + typecheck before opening a PR.'" }
+        ]
+      }
+    ]
+  }
+}

package/ml-specs/templates/mcp/.mcp.json

@@ -0,0 +1,34 @@
+{
+  "//": "Project-scoped MCP config. Copy to the REPO ROOT as .mcp.json and commit it, so every",
+  "//1": "teammate and every MCP-speaking tool (Claude Code, Cursor, a custom agent) gets the same",
+  "//2": "read-only tools over this repo.",
+  "//3": "",
+  "//4": "Replace <ABSOLUTE PATH TO> below with wherever ml-claude-plugins is checked out. If the",
+  "//5": "ml-specs plugin is installed, ${CLAUDE_PLUGIN_ROOT} resolves inside Claude Code — but a",
+  "//6": "non-Claude client won't expand it, so an absolute path is the portable choice.",
+  "//7": "",
+  "//8": "--root . means the server reads THIS repo. Nothing either server exposes writes anything.",
+  "//9": "",
+  "//10": "ml-skills is the ARCHITECTURE STANDARDS half: the rules a spec's contract and the code",
+  "//11": "implementing it are held to. It is OPTIONAL — delete the block if you are not using it —",
+  "//12": "but if you keep it, keep it working: the spec loop reports when the standards could not be",
+  "//13": "consulted rather than passing quietly, because an unrun check is not a clean one.",
+  "mcpServers": {
+    "ml-specs": {
+      "command": "node",
+      "args": [
+        "<ABSOLUTE PATH TO>/ml-claude-plugins/ml-specs/mcp/ml-specs-server.mjs",
+        "--root",
+        "."
+      ]
+    },
+    "ml-skills": {
+      "command": "node",
+      "args": [
+        "<ABSOLUTE PATH TO>/ml-skills/server.mjs",
+        "--root",
+        "."
+      ]
+    }
+  }
+}

package/ml-specs/templates/settings.json

@@ -0,0 +1,18 @@
+{
+  "//": "Committed project settings for Claude Code. Copy to the REPO ROOT as .claude/settings.json",
+  "//1": "and commit it: every teammate who clones the repo gets this with no per-machine setup, and",
+  "//2": "personal overrides still live in .claude/settings.local.json, which this does not touch.",
+  "//3": "",
+  "//4": "attribution — commits and PRs name the humans who own the change. An empty string suppresses",
+  "//5": "that trailer entirely, so no assistant is ever recorded as co-author. This is enforced by",
+  "//6": "Claude Code itself rather than being an instruction a model has to remember, which is why it",
+  "//7": "belongs here and not only in CLAUDE.md.",
+  "//8": "",
+  "//9": "Why it matters beyond one commit: a squash merge aggregates Co-Authored-By trailers from",
+  "//10": "EVERY commit on the branch, so a single stray line added early resurfaces on the merge",
+  "//11": "commit long after, crediting a tool instead of the people who did the work.",
+  "attribution": {
+    "commit": "",
+    "pr": ""
+  }
+}

package/ml-specs/templates/specs/AGENTS.md

@@ -0,0 +1,57 @@
+# The SDD agent team
+
+Spec-driven development as a team of subagents, mapped to the loop:
+
+| Agent | Phase | Command | Tools | Job |
+|-------|-------|---------|-------|-----|
+| `spec-author` | SPECIFY | `/spec` | read + Write | Ticket → reviewable spec under `specs/`. No code. Stops and returns blocking contract questions rather than guessing them. |
+| `spec-reviewer` | SPECIFY | `/spec-review` | read-only + Bash | Adversarially checks the **draft spec** before a human reads it — contracts, testable criteria, ripple. Fresh context, so it sees what the author can't. |
+| `developer` | IMPLEMENT | `/spec-build` | read + Edit/Write + Bash | Builds ONE approved spec, test-first. |
+| `reviewer` | VERIFY | `/spec-verify` | read-only + Bash | Adversarially checks the impl against the spec's acceptance criteria; runs the final-acceptance suite. |
+| `pr-author` | VERIFY | `/pr` | read-only + Bash | Completed spec + diff → PR title/body with the criteria as a checklist. |
+
+The two reviewers are deliberately separate: `spec-reviewer` reviews the **paper** (before code
+exists, where a fix is a sentence), `reviewer` reviews the **code** against that paper.
+
+Definitions live in `.claude/agents/`. Invoke one by asking for it ("use the developer
+agent to build specs/0001-…"), or let Claude pick by description.
+
+## "Three developers working" = parallel implement, isolated
+
+The team had three developers building features concurrently. To mirror that, run **three
+`developer` agents in parallel — one spec each — and give each its own git worktree**
+so their edits never collide:
+
+```
+   ┌─ spec-author  →  specs/0001-a.md ─┐
+   ├─ spec-author  →  specs/0002-b.md ─┤   (human reviews/approves the specs)
+   └─ spec-author  →  specs/0003-c.md ─┘
+                  │  approved
+                  ▼
+   ┌─ developer  (worktree A)  builds 0001 ─┐
+   ├─ developer  (worktree B)  builds 0002 ─┤   run concurrently
+   └─ developer  (worktree C)  builds 0003 ─┘
+                  │  each returns diff + test results
+                  ▼
+   ┌─ reviewer  verifies 0001 ─┐
+   ├─ reviewer  verifies 0002 ─┤   verify per spec
+   └─ reviewer  verifies 0003 ─┘
+                  │
+                  ▼   human merges the approved branches
+```
+
+### Why worktree isolation matters
+Three agents editing the same checkout would clobber each other. Each `developer` runs
+in its own git worktree (a separate working copy on its own branch), so the three streams
+are independent and merge cleanly — exactly like three developers on three branches.
+
+**Important:** parallelize across *independent* specs. If two specs touch the same files
+(e.g. both edit `CouponService`), sequence them instead — paper conflicts are cheaper than
+merge conflicts.
+
+## How to kick it off
+- One ticket: `/spec DLA-1234 …` → review → `/spec-advance … Approved` → `/spec-build specs/NNNN-….md`
+  → `/spec-verify` → `/pr`.
+- A batch (the 3-developer pattern): ask Claude to "spec these 3 tickets, then build them in
+  parallel with isolated worktrees, then review each against its spec." Claude orchestrates
+  the fan-out. For larger batches this is worth running as a structured multi-agent workflow.

package/ml-specs/templates/specs/README.md

@@ -0,0 +1,104 @@
+# Spec-Driven Development (SDD)
+
+Every non-trivial change starts with a **spec** — a reviewable document that defines
+*what* and *why* before any *how* is written. The spec is the contract Claude implements
+against, and the artifact a human reviews **before** code exists.
+
+> One-line / trivial fixes don't need a spec. Anything touching an API, a data model,
+> an event, cross-service behavior, or more than ~one file does.
+
+## The loop
+
+```
+  1. SPECIFY   →   2. PLAN   →   3. IMPLEMENT   →   4. VERIFY
+   (write spec)   (approve)     (code + tests)    (review + CI)
+```
+
+1. **Specify** — `/spec <ticket-or-description>`
+   Claude explores the relevant code, then does two things **before** the spec reaches you:
+
+   - **Asks you the blocking questions up front**, batched, as concrete options with a
+     recommendation. A question is blocking if its answer would change a contract (API shape, data
+     model, error codes, scope, compatibility). Answering four of these in one pass is cheap;
+     discovering them one revision at a time is not.
+   - **Runs an adversarial pass over its own draft** (the `spec-reviewer` agent, fresh context)
+     and fixes what it finds — contract gaps, untestable criteria, unnamed ripple. Hole-finding is
+     the agent's job, not yours.
+
+   Then it writes `specs/NNNN-slug.md` and hands it to you to review and approve. **No
+   implementation code is written in this step.** The spec is the source of truth.
+
+   You should be approving, not QA-ing. If a review keeps turning up holes, that's a bug in the
+   loop — not a reason to review harder.
+
+   `/spec-review specs/NNNN-slug.md` runs that same adversarial pass on demand. `/spec` already
+   does it, so reach for the command when a spec was hand-written, heavily edited, or came from
+   someone else.
+
+   **If you send a spec back:** Claude records what changed in the spec's **Revisions** table, so
+   round two is a diff read rather than another full read.
+
+2. **Plan** — Claude proposes an implementation plan from the approved spec (plan mode).
+   You approve before edits begin.
+
+3. **Implement** — `/spec-build specs/NNNN-slug.md`
+   Claude implements **strictly against the spec's acceptance criteria**, writing a test
+   for each criterion using this project's framework (Java `*Test.java`/`*IT.java`; React/Node
+   Jest/Vitest + Testing Library / Supertest / `@nestjs/testing`). Every user-facing or
+   contract-level criterion also gets a **functional/E2E test** (HTTP black-box, or Playwright/
+   Cypress UI flow), and Claude runs them. Anything not in the spec is out of scope — if a gap
+   surfaces, update the spec first, then continue.
+
+4. **Verify** — `/spec-verify specs/NNNN-slug.md`
+   The `reviewer` agent judges the implementation against the spec's acceptance criteria with
+   fresh context, and runs the **final acceptance** pass (spec section 6.1): the project's *full*
+   test suite, including the functional/E2E tests, green end to end — not just the new tests. Then
+   `/code-review` (and `/security-review` where relevant) and the normal CI pipeline — those check
+   the diff for bugs, which is a different question from "does it match the spec". Run both.
+
+   Then `/spec-advance specs/NNNN-slug.md Verified`, and `/pr specs/NNNN-slug.md` for the PR text
+   with the acceptance criteria as a review checklist.
+
+## Lifecycle
+
+A spec's Status is a claim about reality, so **`/spec-advance` is the only thing that writes it**,
+and each transition has to show its evidence:
+
+| Status | Means | Gate to reach it |
+|--------|-------|------------------|
+| `Draft` | Written, not agreed | — (`/spec` creates it here) |
+| `Approved` | The contract is agreed; build it | Human approval + no blocking question left in §8 |
+| `Implemented` | Code + tests exist for every criterion | Every AC checked, every §6 test named **exists on disk** |
+| `Verified` | It actually works | Clean `/spec-verify` + §6.1 full suite green |
+| `Archived` | Merged and closed out | Branch merged → `git mv` to `specs/archive/NNNN-slug.md` |
+
+If the evidence isn't there, the transition is refused — that's the feature. Moving *backwards*
+(the contract changed mid-build) is fine and needs no gate, but it must add a **Revisions** row.
+`/repo-status` shows where everything sits; `/repo-doctor` flags statuses the repo can't back up.
+
+## Conventions
+
+- Specs are numbered sequentially: `specs/0001-add-coupon-expiry.md`, `specs/0002-...md`. Archiving
+  moves the file to `specs/archive/` but **keeps its number** — numbers are never reused.
+- **The number comes from every branch, not your working tree.** Two people speccing in parallel
+  will otherwise both take the next number and collide at merge — a conflict in a filename, which
+  git resolves badly. `/spec` does this for you; by hand it's:
+  ```
+  git fetch --quiet && git log --all --pretty=format: --name-only --diff-filter=A -- 'specs/[0-9]*' | sort -u
+  ```
+  If a collision does land, renumber the *later* spec and update its branch name — don't merge two
+  specs onto one number.
+- Keep the spec in the **same PR/branch** as the implementation — it documents intent and
+  lives next to the code it describes.
+- A spec is "done" (`Verified`) when every acceptance criterion has a passing test — including a
+  functional/E2E test for each user-facing/contract-level criterion — and the project's full test
+  suite passes end to end (the final-acceptance run, spec section 6.1).
+- Update the spec if reality diverges; a stale spec is worse than none.
+
+## Why this works across many repos and stacks
+
+The same template + the same `/spec` and `/spec-build` commands work in every repo, whatever
+the stack (Java, React, Node/Express, NestJS) and database (MySQL, PostgreSQL, MongoDB). The
+spec captures the contract — API/interface, data model, events, and any cross-service calls —
+explicitly, so changes that ripple between modules or services are designed on paper before
+they're coded.

package/ml-specs/templates/specs/TEMPLATE.md

@@ -0,0 +1,114 @@
+# Spec: <short title>
+
+| | |
+|---|---|
+| **Ticket** | XXX-0000 |
+| **Project / service** | <repo or service name> |
+| **Stack** | <e.g. Java/Spring, React, Node/Express, NestJS — fill from the repo> |
+| **Status** | Draft \| Approved \| Implemented \| Verified \| Archived |
+| **Branch** | <branch this is built on — set by `/spec-advance`; `—` until work starts> |
+| **Author** | <name> |
+| **Date** | YYYY-MM-DD |
+
+> Status is written by `/spec-advance`, which checks the evidence each transition requires
+> (see `specs/README.md`). Don't hand-edit it — a status nobody checked is worth nothing.
+
+## Revisions
+<Skip this section entirely if the spec was approved first pass — it exists only to bound
+re-review. Add one row per revision, newest first, so a reviewer re-reads what moved instead of
+re-reading the whole spec.>
+
+| # | What changed | Why | Sections |
+|---|--------------|-----|----------|
+| 2 | <e.g. 409 → 422 on expired coupon> | <reviewer: 409 implies a conflict that doesn't exist> | 4.1, AC3 |
+| 1 | <initial draft> | — | — |
+
+## 1. Problem / Goal
+<What user/business problem are we solving, and why now? 2–4 sentences. No solution here.>
+
+## 2. Scope
+**In scope**
+- <bullet>
+
+**Non-goals** (explicitly NOT doing)
+- <bullet>
+
+## 3. Current behavior
+<How does the relevant part work today? Reference real code: `path/to/File.ext:42`. If new, say "new".>
+
+## 4. Proposed change
+> Fill only the subsections that apply to this change and this stack. Delete the rest.
+
+### 4.1 API / interface contract
+<The contract this change exposes or consumes. Pick what fits:>
+- **HTTP API** (Java controller, Express route, NestJS controller): method + path, request shape,
+  response shape, status codes, error cases.
+- **UI component / module** (React): component name, props in/out, state, events/callbacks,
+  the data it fetches and from where.
+- **Library/function**: signature, inputs, outputs, errors thrown.
+
+| Method/Type | Path / name | Request / props | Response / return | Notes |
+|-------------|-------------|-----------------|-------------------|-------|
+| | | | | |
+
+### 4.2 Data / state model
+<Pick the row(s) that apply:>
+- **Relational (MySQL/PostgreSQL):** new/changed tables, columns, types, indexes, constraints,
+  and the **migration** (never hand-edited schema). Note transactions where multiple writes
+  must be atomic. Mind dialect specifics (Postgres `SERIAL`/`RETURNING` vs MySQL `AUTO_INCREMENT`).
+- **Document (MongoDB):** new/changed collections, document shape, schema/validation, indexes,
+  and any migration/backfill of existing documents.
+- **Client state (React):** new/changed state shape, where it lives (component, store, cache),
+  and how it's derived/invalidated.
+
+### 4.3 Events / side-effects
+<Async messages, queues/topics, jobs, webhooks, cache invalidation, emails — payload shape,
+idempotency, and failure handling. Omit if none.>
+
+### 4.4 External / cross-service / integration calls
+<Outbound calls to other services or third parties (HTTP client, Feign, SDK). For each: what's
+called, the contract assumed, and failure/timeout behavior. Omit if none.>
+
+### 4.5 Config / feature flags / env
+<New config keys, environment variables (`.env`), feature flags to gate rollout, profiles affected.>
+
+## 5. Acceptance criteria
+<Testable Given/When/Then statements. These become the tests AND the review checklist.>
+
+- [ ] **AC1** — Given <state>, when <action>, then <observable outcome>.
+- [ ] **AC2** — ...
+
+## 6. Test plan
+<Map each AC to at least one test using THIS project's framework. Pick the level that actually
+proves the AC — don't over- or under-test:>
+- **unit** — pure logic in isolation (Java `*Test.java`; Jest/Vitest).
+- **integration** — module + its real collaborators / DB (Java `*IT.java`; Supertest, `@nestjs/testing`).
+- **functional / E2E** — the behavior end to end from the outside, the way a user or caller hits it
+  (HTTP black-box against the running service; UI flows via Playwright/Cypress). **Every
+  user-facing or contract-level AC needs at least one functional/E2E test**, not just a unit test.
+
+| AC | Test type (unit / integration / functional-e2e) | Test file / class / method |
+|----|-------------------------------------------------|----------------------------|
+| AC1 | unit | |
+
+### 6.1 Final acceptance (gate before `Verified`)
+The spec is **not** `Verified` until the project's **full** test suite — including the
+functional/E2E tests above — runs green end to end (not just the newly-added tests). List the
+command(s) that constitute that final run and any seed/fixtures/services they need:
+
+- Full suite: `<e.g. npm test && npm run test:e2e / mvn verify / pytest && pytest -m e2e>`
+- Preconditions: `<test DB seeded, service running, env vars — or "none">`
+
+## 7. Rollout & risks
+<Deploy order if cross-service, backward compatibility, data migration risk, rollback plan,
+and mitigations.>
+
+## 8. Open questions / follow-ups
+<**Non-blocking items only** — things whose answer changes nothing in this spec: a later
+optimization, a question for another team, a deferred follow-up. If an answer would change the API
+shape, data model, error/status codes, scope boundary, or backward compatibility, it is
+**blocking**: it must be answered *before* this spec is written, not parked here. A blocking
+question in this section is a bug — it turns one human review into a review, a revision, and a
+re-read. Empty is the healthy state.>
+
+- <bullet>