checkmate-bdd

checkmate-bdd-plugin

A coding agent plugin for BDD scenario authoring and E2E testing. Project-agnostic — works with any web application, any language, any framework.

All AI work runs inline in your coding agent using the upstream backend's own prompts and Pydantic schemas. No OpenAI API key. No separate AI service. No prompt drift.

Works natively with Claude Code. Also supports GitHub Copilot, Gemini CLI, OpenAI Codex, and other agents via shared instruction files.

How it works

The plugin owns three services — checkmate, playwright-http, and checkmate-mcp — and replaces every OpenAI-dependent feature in those services with an agent skill that reads the backend's own source at runtime.

Your app (native)
     ↑
checkmate :8000  ←  playwright-http :8932
     ↑
checkmate-mcp :3003
     ↑
your coding agent (all AI runs here, reads upstream source from ~/.checkmate-bdd/)

Your application always runs natively. The plugin starts it via stack.start_command in your config and never containerizes it.

Skills

Skill	Trigger	What it does
bdd:setup	Once per project	Create config, clone upstream deps, verify backend source, register MCP server, append agent instruction snippet
bdd:stack	up / down / status	Start/stop checkmate + playwright-http + checkmate-mcp + your app. Pulls latest backend source on up.
bdd:write	Before implementing a feature	Natural language → UTML scenario. Reads planner.py + builder.py from upstream source.
bdd:generate	Starting a new feature area	Bulk-ideate acceptance scenarios. Reads generator.py. Pick which to materialize via bdd:write.
bdd:run	After implementation	Execute scenarios. On failure: classify → heal → retry (up to max_retries). Reads failure_classifier.py + healer.py + reporter.py.
bdd:record	Complex UI flows	Record a browser session, refine raw events into clean UTML. Reads recorder_processor.py + recorder.py.
bdd:ci	Once per repo	Generate GitHub Actions workflow. CI uses run-suite.py directly — no external agent in the loop.

Slash commands

Command	Args	Equivalent
/bdd-stack	up | down | status	bdd:stack skill
/bdd-run	scenario | group | all	bdd:run skill
/bdd-ci	—	bdd:ci skill

Agent

bdd-scenario-writer — specialist subagent for multi-agent workflows. Receives a feature description, returns ready-to-save UTML JSON without interactive back-and-forth. Used by subagent-driven-development plans that need BDD scenarios written before implementation.

Hooks

Hook	Event	Behavior
register-scenario	PostToolUse/Write	Auto-registers any file written to tests/e2e/scenarios/ in checkmate (if stack is running)
check-verification	Stop	If verification_mode: required and checkmate is running, blocks the agent from finishing until bdd:run all passes

Installation

# Install the plugin
claude plugin install https://github.com/joshmullikin/checkmate-bdd-plugin

# Or add via marketplace
claude plugin marketplace add joshmullikin/checkmate-bdd-plugin
claude plugin install checkmate-bdd@checkmate-bdd-marketplace

Then initialize in your project:

claude -p "bdd:setup"

bdd:setup will ask a few questions, clone the upstream service repos to ~/.checkmate-bdd/, wire the MCP server into your agent's settings, and append usage instructions to whichever agent instruction files exist in your project (CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md).

Agent support

The plugin ships with symlinked instruction files so every supported agent reads the same content — no duplication:

File	Agent
CLAUDE.md	Claude Code (canonical source)
AGENTS.md	OpenAI Codex and generic agents
GEMINI.md	Gemini CLI
.github/copilot-instructions.md	GitHub Copilot

AGENTS.md, GEMINI.md, and .github/copilot-instructions.md are git symlinks pointing to CLAUDE.md. bdd:setup replicates the same pattern in your project.

Typical workflow

1. bdd:setup          ← once per project
2. bdd:stack up       ← start services
3. bdd:generate       ← ideate scenarios for a feature
4. bdd:write          ← materialize each scenario (before writing code)
5. [implement]
6. bdd:run all        ← verify
7. bdd:stack down     ← stop services

In CI, steps 2–6 run headlessly via the generated GitHub Actions workflow.

Configuration

tests/e2e/checkmate.config.json (created by bdd:setup):