{"id":15394,"library":"tdd-guard","title":"TDD Guard","description":"TDD Guard is an npm package providing automated Test-Driven Development enforcement for AI agents, specifically within the Claude Code environment. It is currently at version 1.6.3 and exhibits a rapid release cadence, with frequent updates addressing bugs, introducing new features, and enhancing refactoring capabilities. Its primary function is to ensure AI agents adhere strictly to TDD principles by proactively blocking actions that violate test-first or minimal implementation rules, such as adding code without accompanying failing tests or implementing beyond the scope of current test requirements. Key differentiators include its broad multi-language support (e.g., JavaScript, TypeScript, Ruby, Python, Go, Rust, PHP) and integration with numerous test frameworks (including Vitest, Jest, RSpec, and PHPUnit). The package also offers customizable validation rules, lint integration for automated refactoring support, and granular control over validation models and session management.","status":"active","version":"1.6.3","language":"javascript","source_language":"en","source_url":"https://github.com/nizos/tdd-guard","tags":["javascript","tdd","test-driven-development","claude","claude-code","hooks","testing","ai-tools","code-quality","typescript"],"install":[{"cmd":"npm install tdd-guard","lang":"bash","label":"npm"},{"cmd":"yarn add tdd-guard","lang":"bash","label":"yarn"},{"cmd":"pnpm add tdd-guard","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency for integrating with Claude Code. Pinned to specific versions in the past to mitigate upstream native-binary resolver bugs.","package":"@anthropic-ai/claude-agent-sdk","optional":false}],"imports":[{"note":"The `VitestReporter` is a named export from the dedicated 'tdd-guard/vitest' entry point. The constructor signature changed significantly in `tdd-guard-vitest` v0.2.0.","wrong":"import { VitestReporter } from 'tdd-guard';\nconst VitestReporter = require('tdd-guard/vitest');","symbol":"VitestReporter","correct":"import { VitestReporter } from 'tdd-guard/vitest';"},{"note":"Load language-specific reporters from their respective sub-paths. `tdd-guard` is primarily ESM-first for its exposed utilities.","wrong":"const RspecReporter = require('tdd-guard/rspec');","symbol":"RspecReporter","correct":"import { RspecReporter } from 'tdd-guard/rspec';"},{"note":"Ensure named imports for specific reporters, as they are not default exports from their sub-modules.","wrong":"import MinitestReporter from 'tdd-guard/minitest';","symbol":"MinitestReporter","correct":"import { MinitestReporter } from 'tdd-guard/minitest';"}],"quickstart":{"code":"/plugin marketplace add nizos/tdd-guard\n/plugin install tdd-guard@tdd-guard\n/tdd-guard:setup\n\n# After installation, you might need to restart your terminal session or IDE extension for the setup skill to appear.\n# You can then start a Claude Code session, and TDD Guard will begin enforcing TDD principles.\n# Example: If you try to write code without a failing test, it will block the action.","lang":"javascript","description":"Demonstrates the initial setup commands within Claude Code to install and configure TDD Guard."},"warnings":[{"fix":"Update `VitestReporter` instantiation from `new VitestReporter('/path/to/project')` to `new VitestReporter({ projectRoot: '/path/to/project' })` in your `vitest.config.ts` or similar.","message":"The `VitestReporter` constructor signature changed in `tdd-guard-vitest` v0.2.0. It now expects a single options object `{ projectRoot: string }` instead of a direct path string or `Storage` instance.","severity":"breaking","affected_versions":">=vitest-v0.2.0"},{"fix":"Back up your custom `instructions.md`, delete the old file, and start a new Claude Code session to regenerate the default, updated instructions. Then, manually reapply your customizations.","message":"Customized validation rules in `.claude/tdd-guard/data/instructions.md` are not automatically updated when the plugin is upgraded. This means new improvements or bug fixes to the core validation logic may not apply.","severity":"gotcha","affected_versions":">=1.6.1"},{"fix":"Upgrade to TDD Guard v1.6.3 or newer to benefit from improved refactor recognition during green-state operations. If on an older version, be mindful of these blocks and adjust your workflow or update the plugin.","message":"Older versions of TDD Guard (pre-1.6.x) frequently blocked legitimate refactoring activities, such as moving type declarations, extracting functions, or tidying tests, as 'premature implementation'.","severity":"gotcha","affected_versions":"<1.6.3"},{"fix":"Ensure your development environment is running Node.js 22.0.0 or a newer compatible version. Use a version manager like `nvm` to easily switch Node.js versions.","message":"TDD Guard requires Node.js version 22 or higher to run. Using older Node.js versions will result in installation or runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade to TDD Guard v1.5.1 or newer to mitigate this security vulnerability related to file system operations.","message":"A Time-of-Check to Time-of-Use (TOCTOU) race condition in file content reading (CodeQL `js/file-system-race`) was identified and patched.","severity":"security","affected_versions":"<1.5.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure a failing test is present that requires the new code. If refactoring, ensure you are on TDD Guard v1.6.3+ which has improved refactor recognition. Consider the 'adjusting an implementation's signature' or 'tidying existing tests' patterns now allowed.","cause":"Attempting to add or modify implementation code before a corresponding failing test exists, or engaging in certain refactor patterns not recognized by older validator versions.","error":"Plugin blocked action: Premature implementation. Add a failing test first."},{"fix":"Update your Node.js installation to version 22.0.0 or later. Use a Node.js version manager like `nvm` (`nvm install 22 && nvm use 22`) for easier management.","cause":"The system's Node.js version does not meet the minimum requirement specified in the package's `engines` field.","error":"Error: Node.js version is too old. TDD Guard requires Node.js >=22.0.0."},{"fix":"Backup your custom `instructions.md` file. Delete the original `.claude/tdd-guard/data/instructions.md`. Start a new Claude Code session to let TDD Guard regenerate the latest default instructions. Then, manually re-apply your specific customizations to the new file.","cause":"After updating TDD Guard, the custom `instructions.md` file was not refreshed or merged with new default rules, leading to unexpected validation behavior.","error":"Custom validation rules in .claude/tdd-guard/data/instructions.md are not working or outdated."}],"ecosystem":"npm"}