Development & Contribution Guide

Relevant source files

The following files were used as context for generating this wiki page:

• DEVELOPMENT.md
• CONTRIBUTING.md
• CLAUDE.md
• package.json
• README.md
• reporters/go/cmd/tdd-guard-go/main.go
• reporters/rust/src/main.rs

TDD Guard is an automated Test-Driven Development (TDD) enforcement tool designed for Claude Code. It functions as a hook that intercepts file operations (Write, Edit, MultiEdit), analyzes the proposed changes against previous test results, and blocks actions that violate TDD principles like over-implementation or skipping the "Red" phase.

Sources: README.md:1-20, CLAUDE.md:3-12

The project is structured as a TypeScript-based core application supported by multiple language-specific reporters. This guide outlines the requirements and processes for contributing to the core logic and expanding reporter support.

Sources: CLAUDE.md:33-58

Core Development Principles

Contributors must adhere to strict TDD principles when modifying the codebase. This means implementation must be test-driven, with all affected tests passing before submission. The project enforces high code quality through linting, formatting, and mandatory build checks.

Sources: CONTRIBUTING.md:3-7

Workflow and Commit Standards

• Atomic Commits: Each commit should represent one logical change bundled with its corresponding tests.
• Conventional Commits: Use standard prefixes (feat, fix, refactor, etc.) and focus the message on the reason for the change rather than a description of the code.
• Test Proximity: Never separate tests from the implementation code they verify.

Sources: CONTRIBUTING.md:16-18, CLAUDE.md:17-25

Development Environment Setup

The project supports development via Node.js 22+ and offers a pre-configured Dev Container for a consistent environment across different platforms.

Sources: DEVELOPMENT.md:5-20

Building the Project

Before running tests, you must install dependencies and build the TypeScript packages, including all workspace-based reporters (Jest, Vitest, Storybook).

# Install dependencies
npm install

# Build the main package and all workspaces
npm run build

Sources: DEVELOPMENT.md:22-31, package.json:44-45

Testing Infrastructure

The testing suite is divided into core logic tests and language-specific reporter tests.

Command	Scope
npm test	Runs all unit and base integration tests.
npm run test:unit	Fast execution of unit tests only.
npm run test:reporters	Validates all language-specific test result collectors.
npm run checks	Full suite: typecheck, lint, format, and test.

Sources: DEVELOPMENT.md:33-43, CLAUDE.md:69-80, package.json:46-60

Reporter Development

Reporters are responsible for capturing test results from various frameworks and saving them to .claude/tdd-guard/data/test.json in a format the core validator can understand.

Sources: README.md:109-110, reporters/rust/src/main.rs:188-198

Security and Path Validation

For security, reporters must validate that the project root path provided is an absolute path. They must also ensure the current working directory is either the project root or a descendant of it to prevent unauthorized file access.

Sources: CONTRIBUTING.md:20-22, reporters/go/cmd/tdd-guard-go/main.go:88-102

Implementation Flow: Go & Rust Reporters

Language-specific reporters generally follow a pattern of piping test output, parsing it (often from JSON), and transforming it into the TDD Guard contract.

Reporter Requirements by Language

Each reporter has specific environment requirements for development and testing:

• Go: Go 1.21+; build via go build -C reporters/go ./cmd/tdd-guard-go.
• Python: Python 3.8+; requires venv and pytest.
• Rust: Rust 1.70+; build via cargo build --release --manifest-path reporters/rust/Cargo.toml.
• PHP: PHP 8.1+ and Composer.

Sources: DEVELOPMENT.md:5-13, DEVELOPMENT.md:49-65

Contribution Guidelines for Pull Requests

To maintain code quality and ease of review, the project enforces specific PR standards:

1. Scope: PRs must be focused and small. Large, sweeping changes are discouraged.
2. Documentation: Descriptions must explain both the "what" and the "why." Design decisions or architectural choices must be documented.
3. No Emojis: Code and documentation must remain professional and free of emojis.
4. Integration Tests: When adding or modifying a reporter, relevant cases must be added to the reporter integration tests.

Sources: CONTRIBUTING.md:9-14, CONTRIBUTING.md:23-24, CONTRIBUTING.md:26-28

Project Architecture Overview

The repository is organized into a core TypeScript application and a series of reporters.

Summary

The TDD Guard project relies on a highly disciplined development approach to reflect the principles it enforces. Contributions are expected to be test-driven and architecturally sound, ensuring that both the core AI-driven validation and the multi-language test reporters maintain a high standard of reliability.

Sources: CONTRIBUTING.md:3-7, CLAUDE.md:83-88