Initial commit
This commit is contained in:
Zhongwei Li
340
skills/tdd-automation/README.md
Normal file
340
skills/tdd-automation/README.md
Normal file
@@ -0,0 +1,340 @@
|
||||
# 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 <!-- 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:
|
||||
|
||||
```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
|
||||
Reference in New Issue
Block a user