playbooks

home / skills / vudovn / antigravity-kit / tdd-workflow

tdd-workflow skill

/.agent/skills/tdd-workflow

This skill guides you through a TDD workflow, applying RED-GREEN-REFACTOR cycles to write tests first and improve code quality.

npx playbooks add skill vudovn/antigravity-kit --skill tdd-workflow

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.7 KB
---
name: tdd-workflow
description: Test-Driven Development workflow principles. RED-GREEN-REFACTOR cycle.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---

# TDD Workflow

> Write tests first, code second.

---

## 1. The TDD Cycle

```
🔴 RED → Write failing test
    ↓
🟢 GREEN → Write minimal code to pass
    ↓
🔵 REFACTOR → Improve code quality
    ↓
   Repeat...
```

---

## 2. The Three Laws of TDD

1. Write production code only to make a failing test pass
2. Write only enough test to demonstrate failure
3. Write only enough code to make the test pass

---

## 3. RED Phase Principles

### What to Write

| Focus | Example |
|-------|---------|
| Behavior | "should add two numbers" |
| Edge cases | "should handle empty input" |
| Error states | "should throw for invalid data" |

### RED Phase Rules

- Test must fail first
- Test name describes expected behavior
- One assertion per test (ideally)

---

## 4. GREEN Phase Principles

### Minimum Code

| Principle | Meaning |
|-----------|---------|
| **YAGNI** | You Aren't Gonna Need It |
| **Simplest thing** | Write the minimum to pass |
| **No optimization** | Just make it work |

### GREEN Phase Rules

- Don't write unneeded code
- Don't optimize yet
- Pass the test, nothing more

---

## 5. REFACTOR Phase Principles

### What to Improve

| Area | Action |
|------|--------|
| Duplication | Extract common code |
| Naming | Make intent clear |
| Structure | Improve organization |
| Complexity | Simplify logic |

### REFACTOR Rules

- All tests must stay green
- Small incremental changes
- Commit after each refactor

---

## 6. AAA Pattern

Every test follows:

| Step | Purpose |
|------|---------|
| **Arrange** | Set up test data |
| **Act** | Execute code under test |
| **Assert** | Verify expected outcome |

---

## 7. When to Use TDD

| Scenario | TDD Value |
|----------|-----------|
| New feature | High |
| Bug fix | High (write test first) |
| Complex logic | High |
| Exploratory | Low (spike, then TDD) |
| UI layout | Low |

---

## 8. Test Prioritization

| Priority | Test Type |
|----------|-----------|
| 1 | Happy path |
| 2 | Error cases |
| 3 | Edge cases |
| 4 | Performance |

---

## 9. Anti-Patterns

| ❌ Don't | ✅ Do |
|----------|-------|
| Skip the RED phase | Watch test fail first |
| Write tests after | Write tests before |
| Over-engineer initial | Keep it simple |
| Multiple asserts | One behavior per test |
| Test implementation | Test behavior |

---

## 10. AI-Augmented TDD

### Multi-Agent Pattern

| Agent | Role |
|-------|------|
| Agent A | Write failing tests (RED) |
| Agent B | Implement to pass (GREEN) |
| Agent C | Optimize (REFACTOR) |

---

> **Remember:** The test is the specification. If you can't write a test, you don't understand the requirement.

Overview

This skill teaches a practical Test-Driven Development (TDD) workflow centered on the RED-GREEN-REFACTOR cycle. It codifies the three laws of TDD and provides concrete rules, patterns, and anti-patterns to apply TDD reliably in TypeScript projects. The goal is to make tests the specification and drive small, safe, and testable changes.

How this skill works

The workflow enforces writing a failing test first (RED), implementing the minimal code to pass it (GREEN), then improving design without changing behavior (REFACTOR). Tests follow the Arrange-Act-Assert (AAA) pattern. The skill also outlines test prioritization, common anti-patterns, and ways to split responsibilities—useful for human teams or multi-agent setups where separate roles create tests, implement code, and refactor.

When to use it

  • Developing a new feature where requirements are evolving
  • Fixing a bug—write the failing test first to reproduce it
  • Implementing complex business logic or algorithms
  • Maintaining code quality during incremental changes
  • Avoid for quick experimental spikes or pure UI layout work

Best practices

  • Always see the test fail before writing implementation (RED)
  • Write only the minimal code to make the test pass (GREEN)
  • Refactor in small steps; keep the test suite green after each change
  • Name tests by expected behavior, not implementation details
  • Prioritize happy path, then error cases, then edge cases

Example use cases

  • Add a new function: write behavior tests, implement minimal logic, then refactor
  • Capture a bug: create a failing test that reproduces the bug, implement fix, refactor to remove duplication
  • Complex refactor: add tests covering current behavior, refactor internals, verify no behavior change
  • Team workflow: split roles—one writes failing tests, another implements, a third focuses on refactoring
  • Prioritize tests: start with happy path tests to validate core behavior quickly

FAQ

What if a test never fails?

If a new test doesn’t fail, it likely doesn’t exercise behavior or is asserting implementation. Revisit the test to ensure it captures observable behavior and initial state triggers failure.

How many assertions per test?

Aim for one behavior per test to keep failures clear. Grouped assertions are acceptable when they verify a single logical outcome.