# Test-Driven Development (TDD) for Codex Plugin Development: The Complete Guide

> Master test-driven development for Codex plugins. Learn the RED-GREEN-REFACTOR cycle to build robust OpenAI plugins with this complete guide.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-29

---

**Test-driven development for Codex plugins is a disciplined workflow that requires writing a failing test before any production code, following the strict RED-GREEN-REFACTOR cycle enforced by the `superpowers:test-driven-development` skill.**

The OpenAI Plugins repository treats TDD as a foundational discipline for building reliable, maintainable extensions. According to the canonical definition in [`plugins/superpowers/skills/test-driven-development/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/test-driven-development/SKILL.md), this workflow ensures every feature is verified, documented, and safe to refactor before reaching production.

## The RED-GREEN-REFACTOR Cycle in Codex Plugins

The TDD skill codifies a three-phase cycle that governs all plugin development. The core rule—`NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST`—is enforced at lines 31-36 of the skill definition, making it impossible to bypass the RED step without violating the workflow.

### RED – Write a Minimal Failing Test

The cycle begins by capturing the exact behavior you want in a test that initially fails. This step forces you to define the plugin's public interface and expected outcomes before implementation exists. According to the source code, skipping this step triggers a workflow violation warning that instructs you to restart with a failing test (see [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) lines 72-80).

### GREEN – Write Just Enough Production Code

Once the test fails for the right reason, write the minimal implementation required to make it pass. The skill emphasizes avoiding premature optimization or extra configuration options during this phase—only the logic strictly necessary for the current test should be added.

### REFACTOR – Clean Without Breaking

With a passing test as your safety net, you can safely restructure code, extract utilities, or introduce generic parameters. The constraint is absolute: tests must remain green throughout the refactoring process. This phase appears at lines 85-92 of the skill documentation, which emphasizes keeping the test suite passing while improving internal implementation quality.

## Why TDD Matters for Plugin Architecture

The OpenAI Plugins codebase treats TDD as architectural infrastructure rather than optional methodology. When you follow this cycle for Codex plugin development, you gain four structural advantages:

- **Safety net** – Tests guard against regressions when the plugin's OpenAPI schema or runtime logic changes
- **Documentation** – Tests serve as executable specifications that show exactly how the plugin's API should be consumed
- **Design guidance** – Writing the test first forces exposure of a clean, minimal public interface rather than leaking implementation details
- **Rapid feedback** – The RED step guarantees you actually exercised the intended behavior, catching missing edge cases before they reach production

## TDD as a Prerequisite Skill

In the repository's skill hierarchy, TDD functions as required background knowledge for advanced capabilities. The `writing-skills` and `systematic-debugging` skills both list TDD as a mandatory prerequisite (see [`plugins/superpowers/skills/writing-skills/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/writing-skills/SKILL.md) lines 18-20). This dependency chain ensures that developers approach documentation and debugging with a test-first mindset, creating proper failing tests before attempting fixes or feature descriptions.

## Code Example: Implementing Retry Logic with TDD

The following example demonstrates the complete cycle using TypeScript and Jest, matching the patterns specified in the TDD skill documentation.

### Step 1: RED – The Failing Test

```typescript
test('retries failed operations 3 times', async () => {
  let attempts = 0;
  const operation = () => {
    attempts++;
    if (attempts < 3) throw new Error('fail');
    return 'success';
  };

  const result = await retryOperation(operation);
  expect(result).toBe('success');
  expect(attempts).toBe(3);
});

```

This test is minimal, names the behavior clearly, and uses real code rather than mocks—exactly what the TDD skill demands for the RED phase.

### Step 2: GREEN – Minimal Implementation

```typescript
async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
  for (let i = 0; i < 3; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === 2) throw e;
    }
  }
  throw new Error('unreachable');
}

```

Only the logic required for the test is added; no extra options, no premature optimization. This satisfies the GREEN requirement of "just enough production code."

### Step 3: REFACTOR – Extraction and Generalization

```typescript
export async function retry<T>(fn: () => Promise<T>, attempts = 3): Promise<T> {
  for (let i = 0; i < attempts; i++) {
    try {
      return await fn();
    } catch (e) {
      if (i === attempts - 1) throw e;
    }
  }
  // unreachable
}

```

Refactoring introduces generic parameters and extracts utilities, but the original test still passes, satisfying the "keep tests green" rule from the skill documentation.

## Summary

- **Test-driven development for Codex plugins** is enforced by the `superpowers:test-driven-development` skill in the OpenAI Plugins repository.
- The **RED-GREEN-REFACTOR** cycle is mandatory, with strict rules against writing production code before a failing test exists.
- **Key source files** include [`plugins/superpowers/skills/test-driven-development/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/test-driven-development/SKILL.md) (lines 31-36, 72-80, 85-92) and prerequisite dependencies in [`writing-skills/SKILL.md`](https://github.com/openai/plugins/blob/main/writing-skills/SKILL.md).
- **Architectural benefits** include regression protection, executable documentation, cleaner public interfaces, and early edge-case detection.
- **Workflow violations** are flagged automatically if developers attempt to skip the RED phase when working on plugin features.

## Frequently Asked Questions

### What happens if I write production code before a test in Codex plugin development?

The system flags this as a workflow violation. According to [`plugins/superpowers/skills/test-driven-development/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/test-driven-development/SKILL.md) lines 72-80, the TDD skill explicitly instructs you to restart the process by writing a failing test first. The rule `NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST` is non-negotiable in this codebase.

### Which specific skills require test-driven development as a prerequisite?

The `writing-skills` and `systematic-debugging` skills both require TDD as mandatory background knowledge. As documented in [`plugins/superpowers/skills/writing-skills/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/writing-skills/SKILL.md) lines 18-20, these higher-level capabilities assume you can create proper failing tests before attempting to document APIs or debug systematic issues.

### How does the REFACTOR phase differ from regular code cleanup?

During REFACTOR, you may restructure implementation details, extract utilities, or introduce generic parameters, but the existing test suite must remain green throughout. Unlike unprotected refactoring, this phase uses your test suite as a safety net, ensuring that behavioral changes do not occur while you improve code quality.

### Can I use mocks during the RED phase of TDD for Codex plugins?

The TDD skill recommends using real code rather than mocks when possible. The example at lines 71-78 of [`SKILL.md`](https://github.com/openai/plugins/blob/main/SKILL.md) demonstrates tests that exercise actual behavior with minimal setup, favoring integration-style tests over heavy mocking to ensure the plugin logic works in realistic scenarios.