When Is the Test-Driven-Development Skill Mandatory in Superpowers?

The test-driven-development skill is mandatory whenever you add or change production code in the obra/superpowers repository, requiring a failing test before any implementation and verification of both red and green states.

The obra/superpowers repository enforces strict test-driven-development (TDD) protocols through its skill system. According to the source code in skills/test-driven-development/SKILL.md, the TDD skill activates automatically and becomes non-optional the moment you touch production code.

Mandatory Scope of the Test-Driven-Development Skill

The TDD skill applies to all production code modifications without exception. The skill definition explicitly scopes mandatory usage to any activity that changes system behavior.

Production Code Changes

According to lines 18-22 in SKILL.md, you must apply the TDD cycle when:

• Adding new features
• Fixing bugs
• Performing refactoring
• Making any behavior change

The rule is absolute: if the production code changes, the TDD skill is mandatory.

The Iron Law Constraint

The source code defines an "Iron Law" at lines 31-35: "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST". This constraint is hard-coded into the skill logic. You cannot write implementation code until a test exists that fails because the feature is missing.

Non-Negotiable Verification Steps

The TDD skill mandates specific verification checkpoints that you cannot skip. The SKILL.md file marks these steps explicitly as MANDATORY in the source documentation.

RED Verification

Before writing any implementation, you must complete the RED phase. Lines 13-15 in SKILL.md require you to:

1. Write the test
2. Run the test suite
3. Watch the test fail

Skipping the RED verification constitutes a rule violation. The test must fail for the correct reason—demonstrating that the feature is genuinely missing.

GREEN Verification

After implementing the minimal code to satisfy the test, you must complete the GREEN phase. According to lines 70-73 in SKILL.md, you must:

1. Run the test suite
2. Watch the test pass
3. Ensure the entire suite remains green

This verification is mandatory. You cannot proceed to refactoring or additional features until the GREEN checkpoint confirms the implementation works.

Exceptions and Edge Cases

The TDD skill allows extremely limited exceptions, but these require explicit human approval rather than automatic exemption.

Prototypes and Generated Code

Lines 24-28 in SKILL.md mention potential exemptions for:

• Throw-away prototypes
• Generated code
• Configuration files

However, these are not automatic exceptions. The source code states you must ask your human partner for explicit approval before skipping TDD for these items. Without that approval, the skill remains mandatory.

Practical Implementation Example

The following example demonstrates the mandatory TDD workflow using the actual skill requirements.

RED Phase – Mandatory Failing Test

Create the test file first. No implementation code may exist before this step.

// tests/retryOperation.test.ts
test('retries a failing operation three times', async () => {
  let attempts = 0;
  const flaky = () => {
    attempts++;
    if (attempts < 3) throw new Error('still failing');
    return 'ok';
  };

  const result = await retryOperation(flaky);
  expect(result).toBe('ok');
  expect(attempts).toBe(3);
});

Run the test suite and verify it fails (mandatory RED verification):

npm test

# Expected: FAIL - retryOperation is not defined

GREEN Phase – Minimal Implementation

Write only enough code to make the test pass.

// src/retryOperation.ts
export 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');
}

Run the test suite and verify it passes (mandatory GREEN verification):

npm test

# Expected: PASS

REFACTOR Phase – Clean While Green

With the mandatory verifications complete, you may now refactor.

// src/retryOperation.ts (refactored)
export async function retryOperation<T>(
  fn: () => Promise<T>, 
  maxAttempts = 3
): Promise<T> {
  let attempt = 0;
  while (true) {
    try {
      return await fn();
    } catch (e) {
      if (++attempt >= maxAttempts) throw e;
    }
  }
}

The test suite must remain green after refactoring.

Summary

• The test-driven-development skill is mandatory for all production code changes in obra/superpowers, including new features, bug fixes, and refactoring.
• The Iron Law prohibits writing production code without a failing test first, as defined in skills/test-driven-development/SKILL.md lines 31-35.
• RED verification (watching the test fail) and GREEN verification (watching the test pass) are explicitly marked as MANDATORY in the skill definition.
• Exceptions for prototypes or generated code require explicit human approval; they are not automatic exemptions.

Frequently Asked Questions

Is the test-driven-development skill mandatory for documentation changes?

No. According to skills/test-driven-development/SKILL.md, the mandatory scope applies specifically to production code changes. Documentation updates, README edits, or comment-only modifications do not trigger the TDD skill requirements, provided they do not alter executable behavior.

Can I skip the RED verification if I am certain the test will fail?

No. Lines 13-15 in SKILL.md explicitly mark the RED verification as MANDATORY. You must run the test suite and observe the failure, even if you are confident in the test logic. This ensures the test fails for the correct reason and validates the test setup.

What happens if I write production code before writing a test?

This violates the Iron Law defined at lines 31-35 in SKILL.md: "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST." The skill engine in lib/skills-core.js treats this as a rule violation. You must discard the implementation, write the failing test, verify the RED state, and then rewrite the minimal code to pass.

Are configuration files exempt from the TDD skill?

Only with explicit human approval. Lines 24-28 in SKILL.md mention that "throw-away prototypes, generated code, or configuration files" might be exempt, but emphasize that you must ask your human partner for approval. Without that explicit permission, the TDD skill remains mandatory for all file modifications.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}