How the Superpowers Test-Driven-Development Skill Enforces the RED-GREEN-REFACTOR Cycle

The Superpowers test-driven-development skill enforces the RED-GREEN-REFACTOR cycle through mandatory verification gates, a DOT state-machine diagram, and an automated checklist that prevents skipping phases or writing production code before failing tests.

The superpowers:test-driven-development skill in the obra/superpowers repository serves as the canonical definition of the TDD workflow. Located in skills/test-driven-development/SKILL.md, this skill hard-codes the RED-GREEN-REFACTOR loop into explicit, mandatory steps that are verified before any production code is accepted.

Explicit Phase Definitions in SKILL.md

The skill defines five mandatory phases between lines 47-70, each with specific entry and exit criteria. An agent cannot proceed to the next phase until the current one is explicitly verified.

The RED Phase (Write a Failing Test)

In the RED phase, the skill mandates writing a minimal test that describes a single behavior and fails immediately. According to lines 71-90, the test must have a clear name and must not pass against existing code. The skill explicitly forbids writing any production code before the test fails.

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

The VERIFY RED Phase (Watch the Failure)

The skill enforces a mandatory verification step between RED and GREEN. Lines 113-124 require running a specific command to confirm the test fails for the expected reason:

npm test path/to/retryOperation.test.ts

If the test passes at this stage, the skill halts progress and requires the test to be rewritten, as a passing test indicates the behavior already exists or the test is invalid.

The GREEN Phase (Write Minimal Code)

Only after VERIFY RED succeeds may the agent enter the GREEN phase. Lines 130-147 mandate writing the smallest amount of code necessary to make the failing test pass. The skill explicitly prohibits over-engineering; lines 150-162 provide a "Bad" example showing what happens when developers implement more than required.

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

The VERIFY GREEN Phase (Watch the Pass)

Before proceeding to REFACTOR, the skill requires VERIFY GREEN (lines 168-180). The same test command is executed again, but this time the skill verifies that only the target test passes and that the entire test suite remains green. Any new failures force the agent to loop back to the GREEN phase.

The REFACTOR Phase (Clean Up)

The final phase, defined in lines 185-193, permits only refactoring actions that do not alter external behavior. The skill requires tests to remain green throughout refactoring, ensuring that structural improvements do not introduce regressions.

Graphical Enforcement via DOT State Machine

The skill encodes phase transitions in a DOT diagram located at lines 49-68. This state machine is interpreted by the Superpowers runtime to automatically gate progress:

RED → VERIFY_RED → GREEN → VERIFY_GREEN → REFACTOR → VERIFY_GREEN → NEXT → RED

The diagram explicitly prevents agents from transitioning directly from RED to GREEN without the VERIFY_RED step, or from skipping REFACTOR entirely. The Superpowers runtime uses this graph to validate that each phase completion signal matches the expected state transition before unlocking the next phase.

Automated Checklist Verification

At lines 328-340, the skill defines a mandatory checklist that is automatically evaluated at the end of each cycle. This checklist includes:

• Confirmation that a failing test was written before production code
• Verification that the test passed only after minimal implementation
• Validation that refactoring did not change test outcomes

If any item is unchecked, the skill forces the agent to restart the cycle from the RED phase. This creates a hard gate that prevents partial or sloppy TDD adherence.

Summary

The Superpowers test-driven-development skill enforces the RED-GREEN-REFACTOR cycle through:

• Explicit phase definitions in SKILL.md that mandate specific actions for each step
• Mandatory verification gates (VERIFY RED and VERIFY GREEN) that halt progress until tests fail or pass as expected
• A DOT state-machine diagram (lines 49-68) that graphically encodes allowed transitions and prevents phase skipping
• Minimal implementation requirements that prohibit over-engineering during the GREEN phase
• An automated end-of-cycle checklist (lines 328-340) that validates complete adherence before allowing the next feature cycle

Frequently Asked Questions

What happens if I write production code before a failing test in the Superpowers TDD skill?

The skill halts execution and requires you to delete the production code. According to lines 71-90 of skills/test-driven-development/SKILL.md, the RED phase explicitly forbids writing any implementation before a failing test exists. The automated checklist at lines 328-340 verifies this sequence and forces a restart if violated.

How does the DOT diagram prevent skipping the REFACTOR phase?

The DOT state machine defined at lines 49-68 encodes transitions as REFACTOR → VERIFY_GREEN → NEXT → RED. There is no direct edge from GREEN to RED, meaning the Superpowers runtime will reject any attempt to transition to the next feature without passing through REFACTOR. The runtime interprets this graph to automatically gate progress.

Can I run all tests at once, or must I verify one at a time?

The skill requires targeted verification. Lines 113-124 and 168-180 specify running npm test path/to/specific.test.ts to isolate the behavior being developed. While the full suite must remain green during VERIFY GREEN, the skill emphasizes verifying the specific failing test first to ensure minimal, focused implementation.

What constitutes a "bad" GREEN phase implementation?

Lines 150-162 of SKILL.md define bad implementations as those that write more code than necessary to pass the current test. The skill prohibits anticipating future requirements, adding speculative abstractions, or handling edge cases not tested. The GREEN phase must produce the "simplest code that passes," with refactoring reserved for the subsequent REFACTOR phase.

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