spencerbeggs/vitest-agent
Vitest test data, coverage analysis, TDD orchestration and notes for LLM coding agents, served by the vitest-agent MCP server and recorded by lifecycle hooks.
Use when reaching any TDD phase transition — spike close, red→green, green→refactor, or discard — required before exiting the phase so each cycle lands as a discrete, greppable commit in git history.
Guide @vitest-agent/plugin configuration including thresholds, targets, output format, and plugin options. Use when setting up or modifying the plugin configuration.
View the resolved @vitest-agent/plugin configuration
Use when working to raise code coverage, target specific uncovered lines, or close the gap against the workspace's configured coverage thresholds and aspirational targets.
Use when tests are failing, when investigating flaky or persistent failures, or when a failure signature needs systematic diagnosis through vitest-agent's test_history, test_errors, and failure_signature_get surfaces.
Map a fuzzy "/tdd <objective>" into a three-tier hierarchy — goals, then behaviors per goal — written to tdd_session_goals and tdd_session_behaviors. Required for non-toy objectives; the orchestrator iterates the red-green-refactor cycle once per behavior.
Produce a single test name in "should <observable behavior>" form from a goal statement. Use when starting the red phase of a TDD cycle and you need a precise, testable name.
Given a clear test name, produce given/when/then scaffolding and an assertion structure. Use after derive-test-name-from-behavior to write the actual test body.
Read a Vitest error, query test_history for prior occurrences, extract assertion shape, and compute a failure signature. Use when a test fails and you need to decide whether it's a new failure, a recurring known one, or flaky.
How to drive the vitest-agent MCP tools correctly — the non-obvious operational facts (run_tests scoping, why subset runs "fail" coverage, the consoleLeaks signal, the VITEST_AGENT_CONSOLE escape hatch, auto-recovered attribution) that otherwise cost trial-and-error. Also use when: Load when operating a project through the vitest-agent MCP tools. Trigger phrases: "run the tests via run_tests", "run_tests filter", "how do I scope a run", "why does my single-file run fail coverage", "coverage threshold on a subset run", "consoleLeaks", "stray console output in tests", "VITEST_AGENT_CONSOLE", "how do I run one test file with vitest-agent", "run_tests return shape", "no-match result", "which tests classified as flaky". Also load at the start of an agent session driving a vitest-agent project, before the first run_tests call.
Required before any production-code edit during the red phase. Forces externalization of "why I think this fix will work" with cited test_error_id and stack_frame_id evidence.
When stuck in red for >5 turns or >3 failed runs without progress, propose reverting the latest production-code edits to restore green and try a smaller step. Use to escape unproductive red sessions.
Invoke run_tests via MCP and surface stable / new-failure / flaky / recovered classifications. Use any time you need to know the current state of the test suite, especially before deciding whether to advance a TDD phase.
Set up @vitest-agent/plugin in the current project
Use when starting any TDD cycle, before writing any test file, editing any production file, running tests, or advancing a phase — required before any of those actions.
Explains the prescribed __test__/ directory layout, test file naming conventions, and how source coverage is derived from the adjacent src/ folder. Applies to files matching: **/__test__/**/*, **/__fixtures__/**/*, **/__snapshots__/**/*
Apply five concrete heuristics to detect tautological tests, mock-rubber-stamps, and tests written after production code. Use after writing a test, before running it, and any time a test passes too easily.