# What you can do with Test Maze over MCP

Test Maze is spec-driven delivery for AI coding agents: it holds your user stories and acceptance
tests, keeps the agent inside them, has a separate verifier grade the work with fixed rules, and
gates the release on results. Once `@testmaze/mcp` connects your coding agent to a workspace, the
agent gains the MCP tools, resources and prompts that run that loop. This page describes that surface
from a user's point of view — *what you can do*, not how it's implemented. Your MCP client always
shows the live, exact list (`tools/list`); this is the map.

## The verify loop

The core idea: your agent builds against a spec, then asks Test Maze to **grade** the build — and
the pass/fail decision is deterministic (no LLM grades its own work).

1. **Model the work** — capture the product, a feature, and its acceptance criteria as test cases.
2. **Build** — your agent writes the code (this happens in your editor, not here).
3. **Run** — Test Maze executes the test cases headlessly as a *test run*.
4. **Verify** — `pdlc.verify` returns a structured **verdict** (pass/fail, failure buckets, a
   reliability KPI, the git SHA/branch it graded, and a `nextStep` telling the agent what to fix).
5. **Repeat** — the agent acts on `nextStep` and re-verifies until the verdict passes.

`pdlc.verify` is the marquee capability: a single call gives a machine-readable verdict your agent
can loop on, with no self-grading.

## Capability areas

The tools group into families. You don't call most of these by hand — your agent does, driven by
the prompts below — but it helps to know what's available.

| Area | What it lets the agent do |
|---|---|
| **Product & features** | Read/update the workspace product (vision, problem, users); create features, sub-features, and user stories (with their breakdown: edge cases, non-functional requirements, dependencies, assumptions, out of scope, risks); set a feature's lifecycle stage (gated by Ready / Done when the workspace enforces them) and link it to a release. |
| **Test cases** | List, read, create (single or batch), update, and delete test cases; waive/un-waive an acceptance-criterion case with a reason. |
| **Test plans & runs** | Bundle cases into a plan; create a test run for a set of cases; read a run's per-case verdicts; record results. |
| **Verify** | `pdlc.verify` — grade a test run into a deterministic verdict envelope with a `nextStep`. |
| **Releases** | Create and edit releases/sprints/milestones (version, markdown release notes); read the **ship gate** (`release.readiness`: linked runs, no high case failing or unexecuted, no open high-severity defect); ship (refused while the gate fails — only a person can override, on the Releases page) or cancel; list them. |
| **Defects** | `defect.create` turns a failed run case into a defect with a bug breakdown, a regression test case and — when the workspace has GitLab connected — a GitLab issue; `defect.list` reads them. Open high-severity defects hold the release. |
| **Spec-based development** | For workspaces that require every change to trace to a story or test case: `spec.status` (policy, active work item, workspace map), `spec.start_work` (declare the story for the branch, get the `Testmaze-Ref` commit trailer), `spec.finish_work` (close it, stating what was not checked), `spec.trace`, `spec.check_commit`. `init` installs the matching Claude Code and git hooks; `spec check-range` is the CI gate. |
| **Product loop** | `product.status` tells the agent where the product as a whole is (assess → review → set goals → fill backlog → measure), the twin of `pdlc.verify` for the whole product. `docs manifest` (CLI) hashes the repo's strategy documents so assessments cite them by content MD5 and go stale when they change. |
| **Story gates** | `userstory.gates` reads a story's Definition of Ready / Done (automatic checks plus the workspace checklist); `userstory.suggest_checklist` adds unticked suggestions — only people tick them. |
| **Coverage & regression** | Find acceptance-criteria coverage gaps for a feature; freeze a run as a must-stay-green regression baseline, unfreeze, or list frozen baselines. |
| **Metrics** | Track product KPIs (e.g. WAU, NPS, MRR) and per-feature metrics; record observations against them. |
| **Media** | List and upload media (screenshots, PRD documents) tied to the workspace. |
| **Workflow shortcuts** | `project.initialize`, `feature.implement`, `feature.verify` — higher-level entry points that return the right next reference for each phase of the loop. |
| **Session** | Read the current PDLC session state and `nextStep`, or list recent sessions in the workspace. |
| **Identity** | `project.whoami` — which workspace, user and token this connection is scoped to. Call it first after switching folders or re-running `init`. |
| **Code quality** | `quality.smell_check` — deterministic smell findings over a file or diff (long method, long parameter list, large class, switch on a type code, message chains, duplicate blocks, dead code, data clumps), each mapped to the refactorings that fix it, plus a checklist of the smells that need judgement. `architecture.advise` — Gang of Four patterns and Fowler refactorings ranked against a design problem, with when-to-use and trade-offs. `kb.search` / `kb.get` for the underlying entries. No LLM runs on the server for any of this. |
| **Exploratory testing** | Your agent drives its **own** browser (e.g. Playwright MCP); Test Maze keeps the record. `exploration.start`, then `exploration.observe` after every action — back come verification of that action, elements with stable Playwright locators, forms with sample values, suggested assertions, coverage against a budget, and ranked next actions (a `hover` action reveals menus). `exploration.finish` freezes the session; `exploration.to_cases` turns it into test cases. Test Maze never launches a browser for this. |

## Resources

Resources are read-only views your agent can pull by URI under the `testmaze://` scheme — e.g. the
product, a feature, a test case, a test run, a release, product/feature metrics, an exploration
session (`testmaze://exploration/<space>/<id>`), and knowledge-base entries
(`testmaze://kb/<space>/pattern/strategy`, `…/smell/long-method`, `…/refactoring/extract-method`).
They let the agent fetch context (the spec it's building toward, the last run's results, how to fix
a smell) without a tool call.

## Guided prompts

Test Maze ships prompts that drive the loop client-side, so the agent runs the right sequence:

- **`product-init`** — stand up the product/workspace model.
- **`feature-spec`** — turn a PRD or description into a feature + acceptance-criteria test cases.
- **`ac-to-testcase`** — expand acceptance criteria into concrete test cases.
- **`find-coverage-gaps`** — surface acceptance criteria that aren't yet covered by a test case.
- **`code-smell-review`** — turn `quality.smell_check` output into a structured review: confirmed and dismissed smells with line evidence, and an ordered refactoring plan.
- **`architecture-review`** — turn `architecture.advise` candidates into one justified recommendation with a migration plan in named refactorings.
- **`explore-feature`** — run a whole exploratory session with your browser tools and record it, ending in test cases.
- **`exploration-to-cases`** — polish exploration-derived test cases before creating them.
- **`spec-driven-change`** — for workspaces that enforce spec-based development: find or create the user story, write its acceptance cases, `spec.start_work`, code, commit with the trailer, let `testmaze-verifier` grade, `spec.finish_work`. Named by `spec.status` and the server instructions.
- **`verify-feature`** — for a separate verifier agent (the `testmaze-verifier` subagent `init` installs): run a feature's acceptance cases, record them with `recordedBy: "verifier"` and grade with `pdlc.verify`, without editing code or test cases.

In Claude Code these appear as slash commands prefixed by the name you registered the server under,
e.g. `/mcp__tm__explore-feature`.

## Where it runs

Everything above runs against your Test Maze workspace over the MCP-over-HTTP transport. This
package is just the stdio↔HTTP bridge — your agent speaks MCP to it, and it forwards to the backend
(default `https://testmaze.com`, override with `--url` on `init`). See [usage.md](https://unpkg.com/@testmaze/mcp@latest/docs/usage.md) for
setup.