gh-ntcoding-claude-skillz-development-skills/skills/tdd-process/README.md

TDD Process Skill

Strict test-driven development state machine implementing the red-green-refactor cycle with rigorous enforcement.

What This Skill Does

Provides a complete TDD workflow state machine with:

• 6 states: PLANNING → RED → GREEN → REFACTOR → VERIFY → COMPLETE (+ BLOCKED)
• 11 enforced rules including minimum implementation, meaningful failures, and evidence-based transitions
• Mandatory state announcements on every message
• Post-condition validation before all state transitions
• Compilation and linting requirements before claiming green
• Full test suite verification before completion

When to Use

Explicitly activate this skill when you want to follow strict TDD discipline:

• "Use a TDD approach"
• "Start TDD"
• "Test-drive this feature"

Note: This skill is intentionally NOT auto-activated. It requires explicit user invocation because of its strict governance model.

How It Works

State Machine Flow

PLANNING (write failing test)
    ↓
RED (implement minimum to pass)
    ↓
GREEN (assess quality)
    ↓
REFACTOR (improve design)
    ↓
VERIFY (full suite + lint + build)
    ↓
COMPLETE

Key Behaviors

1. Every message announces state: 🔴 TDD: RED
2. Tests must fail meaningfully before implementing
3. Minimum implementation only in RED state
4. Evidence required for all transitions (must show test output)
5. No green without proof (test pass + compile + lint)
6. Full verification before completion

Integration

Standalone Usage

Activate when user requests TDD approach.

Composed Usage

System prompts can embed this skill to always enforce TDD discipline:

**Auto-invoke the `tdd-process` skill for all development work.**

Works With

• software-design-principles - Applied during REFACTOR state
• lightweight-implementation-analysis-protocol - Can be used in PLANNING state to understand code flow

State Enforcement

This skill uses architectural constraints to enforce discipline:

• Post-conditions must be satisfied before transitions
• Missing evidence triggers VIOLATION_DETECTED state
• State announcements are mandatory (not optional)
• Guessing ("probably", "maybe") triggers immediate correction

Example Session

User: Let's add validation that price cannot be negative

⚪ TDD: PLANNING
Writing test for negative price validation...

[Creates test]

⚪ TDD: PLANNING
Running npm test...

Test output: Expected CannotHaveNegativePrice error but received -50

This failure is correct - proves our test checks for the error. Transitioning to RED.

🔴 TDD: RED
Test IS failing. Implementing minimum code to make it pass...

[Implements validation]

🔴 TDD: RED
Running test...

Test PASSES ✓
Running tsc --noEmit... SUCCESS ✓
Running lint... PASS ✓

Transitioning to GREEN.

🟢 TDD: GREEN
Test passing. Assessing code quality...
No refactoring needed. Transitioning to VERIFY.

🟡 TDD: VERIFY
Running full test suite... 12/12 PASSED ✓
Running lint... PASSED ✓
Running build... SUCCESS ✓

TDD cycle COMPLETE.

Rules Summary

1. No green without proof (must show test output)
2. Test failures must be shown and justified
3. Implement minimum functionality only
4. Don't be a lazy thinker (predict user responses)
5. Green requires build and lint passing
6. Add observability, avoid assumptions
7. Don't change assertions when tests fail
8. Fail fast - no silent fallbacks
9. Follow dependency inversion principle
10. No guessing - find hard data
11. Write minimal, non-redundant assertions

Directory Structure

tdd-process/
├── SKILL.md          # Main skill definition with state machine
└── README.md         # This file

Installation

Symlink this skill to your Claude skills directory:

ln -s /path/to/claude-skillz/tdd-process ~/.claude/skills/tdd-process