# TDD Workflow

Enforces strict Red-Green-Refactor TDD cycle. Tests first, minimal implementation, then refactor. Inspired by obra/superpowers and Aider architect mode.

## Quick Reference

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

```bash
$ 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

```bash
$ 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