Skill Tdd

Host: Codex CLI — This skill was designed for Claude Code and adapted for Codex. Cross-reference commands use installed skill names in Codex rather than /octo:* slash commands. Use the active Codex shell and subagent tools. Do not claim a provider, model, or host subagent is available until the current session exposes it. For host tool equivalents, see skills/blocks/codex-host-adapter.md.

Test-Driven Development (TDD)

MANDATORY COMPLIANCE — DO NOT SKIP

When this skill is invoked, you MUST run the TDD pipeline through orchestrate.sh (red → green → refactor) with real provider dispatch. You are PROHIBITED from:

• Writing implementation before a failing test exists
• Simulating provider output instead of dispatching via orchestrate.sh
• Declaring the task "too small for TDD" and skipping the cycle without asking the user
• Marking work complete while any test is red or skipped
• Rationalizing that a direct edit is faster — the user invoked TDD for test-first discipline

The Iron Law

Violating the letter of this rule is violating the spirit of this rule.

Write code before the test? Delete it. Start over.

• Don't keep it as "reference"
• Don't "adapt" it while writing tests
• Don't look at it
• Delete means delete

Red-Green-Refactor Cycle

   ┌─────────┐
   │   RED   │ ← Write ONE failing test
   └────┬────┘
        ↓
   ┌─────────┐
   │  VERIFY │ ← Watch it FAIL (mandatory)
   └────┬────┘
        ↓
   ┌─────────┐
   │  GREEN  │ ← Write MINIMAL code to pass
   └────┬────┘
        ↓
   ┌─────────┐
   │  VERIFY │ ← Watch it PASS (mandatory)
   └────┬────┘
        ↓
   ┌─────────┐
   │REFACTOR │ ← Clean up (stay green)
   └────┬────┘
        ↓
     [REPEAT]

Phase 1: RED - Write Failing Test

Write ONE minimal test showing what should happen.

Good Test:

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);
});

• Clear name describing behavior
• Tests real code, not mocks
• One thing only

Bad Test:

test('retry works', async () => {  // Vague name
  const mock = jest.fn()           // Tests mock, not code
    .mockRejectedValueOnce(new Error())
    .mockResolvedValueOnce('success');
  // ...
});

Phase 1.5: Adversarial Test Design Review (RECOMMENDED)

After writing the initial test(s) but BEFORE verifying they fail, challenge the test design with a second provider. A single-model test suite often has systematic blind spots — the same model that writes the tests will write implementation that trivially satisfies them. An adversarial review catches scenarios that would pass with a stub that doesn't actually work.

If an external provider is available, dispatch the test specs for challenge:

review_provider=""
command -v codex >/dev/null 2>&1 && review_provider="codex"
[[ -z "$review_provider" ]] && command -v agy >/dev/null 2>&1 && review_provider="agy"
[[ -z "$review_provider" ]] && command -v gemini >/dev/null 2>&1 && review_provider="gemini"

if [[ -n "$review_provider" ]]; then
  "${HOME}/.claude-octopus/plugin/scripts/orchestrate.sh" spawn "$review_provider" \
    "Review these test specifications for a TDD workflow. Your job is to find gaps, not confirm quality.

1. What SCENARIOS are missing? (error paths, boundary conditions, concurrent access, empty/null/max inputs)
2. What BOUNDARY CONDITIONS are untested? (off-by-one, integer overflow, empty strings, max-length strings)
3. Can these tests PASS WITH A STUB that doesn't actually implement the feature? If yes, what test would catch the stub?
4. Do the tests verify BEHAVIOR or IMPLEMENTATION? (Tests should verify what, not how)

TEST SPECS:
<paste test code here>"
fi

After receiving the challenge:

• Add any genuinely missing test cases to the RED phase
• Strengthen any tests that could pass with a trivial stub
• Dismiss challenges that test implementation details rather than behavior

Skip with --fast or when user requests speed over thoroughness.

Phase 2: VERIFY RED - Watch It Fail

MANDATORY. Never skip.

npm test path/to/test.test.ts

Confirm:

• Test fails (not errors)
• Failure message is what you expected
• Fails because feature is missing (not typos)

Phase 3: GREEN - Minimal Code

Write the simplest code to pass the test. Nothing more.

Good:

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');
}

Bad (YAGNI violation):

async function retryOperation<T>(
  fn: () => Promise<T>,
  options?: {
    maxRetries?: number;           // Not needed yet
    backoff?: 'linear' | 'expo';   // Not needed yet
    onRetry?: (n: number) => void; // Not needed yet
  }
): Promise<T> { /* ... */ }

Phase 4: VERIFY GREEN - Watch It Pass

MANDATORY.

npm test path/to/test.test.ts

Confirm:

• Test passes
• All other tests still pass
• Output is clean (no errors, warnings)

Phase 5: REFACTOR - Clean Up

Only after GREEN:

• Remove duplication
• Improve names
• Extract helpers

Keep tests green throughout. Don't add new behavior.

Common Rationalizations

Strategy Rotation

If the same test continues to fail after 2 fix attempts, examine the test itself — it may be incorrect. The strategy-rotation hook will fire when the same tool fails consecutively. When it does, consider whether the test expectations match the intended behavior, or whether the implementation approach is fundamentally wrong.

Red Flags - STOP and Start Over

If you catch yourself:

• Writing code before test
• Test passes immediately (didn't watch it fail)
• Rationalizing "just this once"
• "I already manually tested it"
• "Keep as reference" or "adapt existing code"
• "This is different because..."

ALL of these mean: Delete code. Start over with TDD.

Bug Fix Example

Bug: Empty email accepted

RED:

test('rejects empty email', async () => {
  const result = await submitForm({ email: '' });
  expect(result.error).toBe('Email required');
});

VERIFY RED:

$ npm test
FAIL: expected 'Email required', got undefined

GREEN:

function submitForm(data: FormData) {
  if (!data.email?.trim()) {
    return { error: 'Email required' };
  }
  // ...
}

VERIFY GREEN:

$ npm test
PASS

Verification Checklist

Before marking work complete:

• Every new function/method has a test
• Watched each test fail before implementing
• Each test failed for expected reason
• Wrote minimal code to pass each test
• All tests pass
• Output clean (no errors, warnings)

Can't check all boxes? You skipped TDD. Start over.

Integration with Claude Octopus

When using octopus workflows:

When Stuck

The Bottom Line

Production code exists → Test exists that failed first
Otherwise → Not TDD

No exceptions without explicit user permission.

Source: hashgraph-online/awesome-codex-plugins → plugins/nyldn/claude-octopus/skills/skill-tdd/SKILL.md