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:

🔴 RED Phase - Writes failing tests FIRST
🟢 GREEN Phase - Implements minimal code to pass tests
🔵 REFACTOR Phase - Improves code quality while keeping tests green

No slash commands. No manual prompting. Just say "implement X" and TDD happens.

Installation

# 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

{
  "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

# Check if project follows TDD practices
npm run validate:tdd

Test Generation

# Generate test template for implementation file
npm run generate:test src/features/auth/login.ts

Maintenance

# 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:

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:

{
  "testCommand": "jest",
  "testExtension": ".test.ts"
}

Troubleshooting

Issue: LLM not following TDD

Solution:

Check CLAUDE.md has TDD configuration:

grep -A 5 "TDD_AUTOMATION" .claude/CLAUDE.md

Verify npm scripts installed:
```
npm run test:tdd
```
Validate installation:
```
npm run validate:tdd
```

Issue: Git hook blocking commits

Solution:

Ensure tests exist for implementation files

Commit tests before implementation:

git add src/**/*.test.ts
git commit -m "Add tests for feature X"
git add src/**/!(*test).ts
git commit -m "Implement feature X"

Or bypass hook temporarily:
```
git commit --no-verify
```

Issue: Want to remove TDD automation

Solution:

# 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 <!-- TDD_AUTOMATION_START --> and <!-- TDD_AUTOMATION_END -->
# 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:

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