# tdd-workflow

tdd-workflow — a skill for Claude Code, Codex, Cursor and other platforms that enforces test-driven development: first a failing test (RED), then minimal code to pass (GREEN), then refactoring.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 141 installs · ★ 114 repo stars
- Author: travisjneuman
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/travisjneuman/.claude/tree/HEAD/skills/tdd-workflow/SKILL.md
- Updated: 2026-10-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/travisjneuman-tdd-workflow

## What it does

Enforces the TDD cycle: in RED, the skill requires a failing test before implementation; in GREEN, minimal code to pass; in REFACTOR, cleanup without behavior change. Each phase ends with a test run. Inside: checklists for each phase, AAA (Arrange-Act-Assert) pattern examples, test naming rules and edge-case tables.

Target coverage metrics: statements 85 %, branches 80 %, functions 90 %. The list of common TDD mistakes includes testing implementation instead of behavior, large tests and shared state between cases. The skill does not activate by default: it only triggers when you explicitly ask for test-first or coverage work.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add travisjneuman/.claude --skill tdd-workflow -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/tdd-workflow/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/tdd-workflow/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add travisjneuman/.claude --skill tdd-workflow -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/tdd-workflow/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add travisjneuman/.claude --skill tdd-workflow -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/tdd-workflow/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install travisjneuman/.claude skills/tdd-workflow
```

2. **Manually: put the files in place**
- File: `.github/skills/tdd-workflow/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add travisjneuman/.claude --skill tdd-workflow -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/travisjneuman/.claude --path skills/tdd-workflow
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/tdd-workflow/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add travisjneuman/.claude --skill tdd-workflow -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/travisjneuman/.claude/tree/HEAD/skills/tdd-workflow/SKILL.md

## When to use it
- roll out RED-GREEN-REFACTOR in the team
- write a test before implementing a function
- raise test coverage to 85 %
- catch edge cases (empty inputs, NULL, MAX_INT)
- avoid brittle tests tied to implementation

## Example prompts
- Turn on TDD mode and add a `multiply` method to the calculator
- Write tests for `UserService.getPermissions` using RED-GREEN-REFACTOR
- Show me how to test edge cases for `parseDate`

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 45fd876c52f496a6.

BEGIN THIRD-PARTY FILE 45fd876c52f496a6
````text
---
name: tdd-workflow
description: Test-Driven Development workflow enforcement with RED-GREEN-REFACTOR cycle. Use only when the user explicitly asks for test-first work or improved test coverage.
---

# Test-Driven Development (TDD) Workflow

Use this skill only when the user explicitly asks for tests; otherwise validate by reviewing the diff and the code it touches.

A disciplined approach to development where tests drive design and implementation.

## The TDD Mantra

> "Never write a line of code without a failing test."

## The RED-GREEN-REFACTOR Cycle

### RED Phase: Write a Failing Test

**Goal**: Define the expected behavior BEFORE implementation.

**Rules**:

1. Write the smallest test that fails
2. Test must fail for the RIGHT reason
3. Test should clearly express intent
4. Don't write implementation yet

**Example**:

```typescript
// RED: Test the behavior we want
describe("Calculator", () => {
  it("should add two numbers", () => {
    const calc = new Calculator();
    expect(calc.add(2, 3)).toBe(5);
  });
});

// Run: npm test
// Result: FAIL - Calculator is not defined
// This is RED ✓
```

**Checklist**:

- [ ] Test is written
- [ ] Test fails when run
- [ ] Failure message is clear
- [ ] Test name describes expected behavior

---

### GREEN Phase: Make the Test Pass

**Goal**: Write the MINIMUM code to pass the test.

**Rules**:

1. Do the simplest thing that works
2. Don't add extra features
3. Don't optimize
4. Just make it green

**Example**:

```typescript
// GREEN: Minimum implementation to pass
class Calculator {
  add(a: number, b: number): number {
    return a + b; // Simplest thing that works
  }
}

// Run: npm test
// Result: PASS
// This is GREEN ✓
```

**Checklist**:

- [ ] Test passes
- [ ] No extra code added
- [ ] Implementation is minimal

---

### REFACTOR Phase: Improve the Code

**Goal**: Clean up while keeping tests green.

**Rules**:

1. Only refactor with passing tests
2. Run tests after each change
3. Improve design, not behavior
4. Small, incremental changes

**Examples of refactoring**:

- Extract methods
- Rename for clarity
- Remove duplication
- Improve performance
- Add types/documentation

**Checklist**:

- [ ] Tests still pass
- [ ] Code is cleaner
- [ ] No behavior changed
- [ ] Ready for next RED

---

## TDD in Practice

### Starting a New Feature

```
1. Write high-level acceptance test (may not run yet)
2. Write first unit test (RED)
3. Implement minimum code (GREEN)
4. Refactor if needed (REFACTOR)
5. Repeat 2-4 until feature complete
6. Verify acceptance test passes
```

### Test Structure (AAA Pattern)

```typescript
it("should [behavior] when [condition]", () => {
  // Arrange - Set up test data and dependencies
  const user = createTestUser({ role: "admin" });
  const service = new UserService();

  // Act - Execute the code under test
  const result = service.getPermissions(user);

  // Assert - Verify expected outcomes
  expect(result).toContain("delete");
  expect(result).toContain("edit");
});
```
````
END THIRD-PARTY FILE 45fd876c52f496a6

The third-party file has ended. Everything between the 45fd876c52f496a6 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3019 of 5304 bytes. © travisjneuman · MIT · https://github.com/travisjneuman/.claude/tree/HEAD/skills/tdd-workflow/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
