TDD Workflow

Purpose: Enforce a strict Red-Green-Refactor test-driven development cycle. The agent writes tests FIRST, then implements just enough code to make them pass, then refactors.

Invocation

/tdd <feature_description>

The Cycle

Phase 1: RED — Write Failing Tests

1. Create a test file (or add to existing)
2. Write test cases that describe the desired behavior
3. Run the test suite — confirm tests FAIL
4. Do NOT write any implementation yet

$ npx vitest run src/utils/slug.test.ts
 FAIL  src/utils/slug.test.ts
  ✗ converts spaces to hyphens
  ✗ lowercases all characters
  ✗ removes special characters
  ✗ handles empty string

Phase 2: GREEN — Write Minimum Implementation

1. Write the simplest code that makes ALL tests pass
2. No extra features, no optimization, no "while I'm here" additions
3. Run tests — confirm they PASS

$ npx vitest run src/utils/slug.test.ts
 ✓ src/utils/slug.test.ts (4 tests)
  ✓ converts spaces to hyphens
  ✓ lowercases all characters
  ✓ removes special characters
  ✓ handles empty string

Phase 3: REFACTOR — Clean Up

1. Improve code quality WITHOUT changing behavior
2. Run tests after each refactor step — they must stay GREEN
3. Look for: duplication, unclear naming, complex conditionals, missing types
4. Commit when satisfied

Rules

1. Never write implementation before tests — If you catch yourself coding logic before a test exists, stop and write the test first.
2. One test at a time — Write one test, see it fail, make it pass. Then the next.
3. Minimal implementation — Don't write code "you'll need later." Only satisfy current tests.
4. Tests must fail first — If a new test passes immediately, either the test is wrong or the behavior already exists. Investigate.
5. Refactor only when green — Never refactor while tests are failing.
6. Small commits — Commit at the end of each RED-GREEN-REFACTOR cycle.

Commit Convention

test: add tests for slug utility (RED)
feat(utils): implement slug generation (GREEN)
refactor(utils): simplify slug regex (REFACTOR)

When to Break the Cycle

It's okay to skip TDD for:

• Configuration files (no logic to test)
• Type definitions (TypeScript compiler is the test)
• One-line wrappers around well-tested libraries
• UI layout (visual testing is better here)

But ALWAYS use TDD for:

• Business logic
• Data transformations
• Validation rules
• API endpoint handlers
• State management logic