Initial commit

skills/tdd-process/README.md

@@ -0,0 +1,146 @@
+# 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:
+
+```markdown
+**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:
+
+```bash
+ln -s /path/to/claude-skillz/tdd-process ~/.claude/skills/tdd-process
+```