# TDD Red-Green-Refactor Automation Automated TDD enforcement for LLM-assisted development. This skill installs infrastructure that guides Claude Code to automatically follow TDD workflow without manual intervention. ## Version **0.2.0** - Stable release with comprehensive safety features ## What This Skill Does Transforms your project so that when you ask Claude to implement features, it **automatically**: 1. 🔴 **RED Phase** - Writes failing tests FIRST 2. 🟢 **GREEN Phase** - Implements minimal code to pass tests 3. 🔵 **REFACTOR Phase** - Improves code quality while keeping tests green **No slash commands. No manual prompting. Just say "implement X" and TDD happens.** ## Installation ```bash # From claudex marketplace /plugin install tdd-automation # Or directly invoke the skill tdd-automation ``` ## What Gets Installed ### 1. CLAUDE.md Configuration - Adds TDD requirements to project's `.claude/CLAUDE.md` - **Safety**: Backs up existing files, merges cleanly, fully reversible - Configures LLM to automatically follow TDD workflow ### 2. npm Scripts ```json { "test:tdd": "vitest --run", "test:tdd:watch": "vitest", "test:red": "vitest --run --reporter=verbose", "test:green": "vitest --run --reporter=verbose", "validate:tdd": "node .tdd-automation/scripts/validate-tdd.js", "generate:test": "node .tdd-automation/scripts/generate-test.js" } ``` ### 3. Git Hooks - **Pre-commit hook**: Validates tests exist before allowing commits - Prevents TDD violations at the version control level - Can be bypassed with `--no-verify` if needed ### 4. Helper Scripts ``` .tdd-automation/ ├── scripts/ │ ├── generate-test.js # Create test templates │ ├── validate-tdd.js # Check compliance │ ├── rollback-tdd.js # Restore previous state │ └── remove-tdd-section.js # Clean uninstall └── templates/ └── test-template.js # Test file template ``` ## Usage Examples ### Before Installation ``` You: "Add user authentication" Claude: *writes implementation code directly* ❌ ``` ### After Installation ``` You: "Add user authentication" Claude: "I'll implement user authentication following TDD red-green-refactor. Let me create a todo list to track the phases: - [ ] RED: Write failing test for user authentication - [ ] Verify test fails with expected error - [ ] GREEN: Implement minimal authentication logic - [ ] Verify test passes - [ ] REFACTOR: Improve code quality Starting RED phase - I'll create the test file first..." *Creates src/auth/authenticate.test.ts* *Writes failing test* *Runs: npm run test:red* *Verifies failure* "Test is failing as expected. Moving to GREEN phase..." *Implements minimal code* *Runs: npm run test:green* *Verifies pass* "All tests passing. Moving to REFACTOR phase..." *Improves code structure* *Runs: npm run test:tdd* "✅ Feature complete with TDD workflow followed." ``` ## Available Commands ### Validation ```bash # Check if project follows TDD practices npm run validate:tdd ``` ### Test Generation ```bash # Generate test template for implementation file npm run generate:test src/features/auth/login.ts ``` ### Maintenance ```bash # Rollback to previous CLAUDE.md node .tdd-automation/scripts/rollback-tdd.js # Remove only TDD section from CLAUDE.md node .tdd-automation/scripts/remove-tdd-section.js # View available backups ls -lh .claude/CLAUDE.md.backup.* ``` ## Safety Features ### ✅ Non-Destructive Installation - **Automatic backups** before any file modification - **Merge strategy** preserves all existing content - **Clear markers** for easy identification of additions - **Rollback capability** to restore previous state ### ✅ Validation Before Installation - Detects existing TDD automation (skips if present) - Checks for existing CLAUDE.md (merges safely) - Validates project structure - Reports warnings for missing dependencies ### ✅ Clean Uninstallation - Remove TDD section without affecting other content - Restore from timestamped backups - No orphaned files or configurations ## Configuration ### Enforcement Level By default, TDD is **strictly enforced**. To customize: Edit `.claude/CLAUDE.md` and modify: ```yaml tdd-enforcement-level: strict # or: advisory, optional ``` - **strict**: LLM must follow TDD (default) - **advisory**: LLM suggests TDD but allows flexibility - **optional**: TDD is available but not required ### Test Framework The skill auto-detects your test framework: - Vitest (default, recommended) - Jest - Mocha - AVA To override, edit `.tdd-automation/config.json`: ```json { "testCommand": "jest", "testExtension": ".test.ts" } ``` ## Troubleshooting ### Issue: LLM not following TDD **Solution:** 1. Check CLAUDE.md has TDD configuration: ```bash grep -A 5 "TDD_AUTOMATION" .claude/CLAUDE.md ``` 2. Verify npm scripts installed: ```bash npm run test:tdd ``` 3. Validate installation: ```bash npm run validate:tdd ``` ### Issue: Git hook blocking commits **Solution:** 1. Ensure tests exist for implementation files 2. Commit tests before implementation: ```bash git add src/**/*.test.ts git commit -m "Add tests for feature X" git add src/**/!(*test).ts git commit -m "Implement feature X" ``` 3. Or bypass hook temporarily: ```bash git commit --no-verify ``` ### Issue: Want to remove TDD automation **Solution:** ```bash # Option 1: Remove only CLAUDE.md section node .tdd-automation/scripts/remove-tdd-section.js # Option 2: Rollback to previous CLAUDE.md node .tdd-automation/scripts/rollback-tdd.js # Option 3: Manual removal # 1. Edit .claude/CLAUDE.md # 2. Delete section between and # 3. Remove .tdd-automation/ directory # 4. Remove npm scripts from package.json ``` ## Technical Details ### Architecture ``` ┌─────────────────────────────────────────┐ │ User Request │ │ "Implement feature X" │ └──────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ CLAUDE.md (LLM Configuration) │ │ • TDD workflow requirements │ │ • Phase-by-phase instructions │ │ • TodoWrite templates │ └──────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ Claude Code (LLM) │ │ 1. Creates test file │ │ 2. Writes failing test (RED) │ │ 3. Runs: npm run test:red │ │ 4. Implements code (GREEN) │ │ 5. Runs: npm run test:green │ │ 6. Refactors (REFACTOR) │ │ 7. Runs: npm run test:tdd │ └──────────────┬──────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ Git Pre-Commit Hook │ │ • Validates tests exist │ │ • Blocks commits without tests │ │ • Ensures test-first compliance │ └─────────────────────────────────────────┘ ``` ### File Structure ``` project/ ├── .claude/ │ ├── CLAUDE.md # TDD configuration (modified) │ ├── CLAUDE.md.backup.* # Safety backups │ └── hooks/ │ └── tdd-auto-enforcer.sh # Pre-prompt hook (optional) ├── .git/ │ └── hooks/ │ └── pre-commit # TDD validation (modified) ├── .tdd-automation/ # Installed by skill │ ├── scripts/ │ │ ├── generate-test.js │ │ ├── validate-tdd.js │ │ ├── rollback-tdd.js │ │ └── remove-tdd-section.js │ ├── templates/ │ │ └── test-template.js │ └── README.md └── package.json # npm scripts added ``` ## Success Metrics Track TDD adherence: ```bash npm run validate:tdd ``` **Target Metrics:** - Test-first adherence: >95% - RED-GREEN-REFACTOR cycles: >90% - Defect escape rate: <2% - Test coverage: >80% ## Contributing This skill was auto-generated by the Pattern Suggestion Pipeline from 37 successful TDD applications with 86% success rate. **Issues or improvements:** - GitHub: https://github.com/cskiro/claudex/issues - Pattern source: Issue #13 ## License MIT ## Version History - **0.2.0** (2025-11-02) - Stable release with full implementation - Comprehensive safety features (backup, rollback, merge) - Automatic LLM TDD enforcement via CLAUDE.md - Git hooks for pre-commit validation - Helper scripts (generate-test, validate-tdd) - Multi-framework support (Vitest, Jest, Mocha, AVA) - Complete documentation and troubleshooting guide - **0.1.0** (2025-11-02) - Initial proof-of-concept - Auto-generated by Pattern Pipeline - Basic skill structure and manifest