How Plugins Like Superpowers Implement Test-Driven Development Workflows Through Skill Definitions

Superpowers implements test-driven development workflows by encoding RED-GREEN-REFACTOR cycles as declarative YAML and markdown skill definitions that orchestrate subagent behavior without external CI systems.

The openai/plugins repository hosts Superpowers, a plugin architecture that treats software development workflows as data rather than imperative code. By defining skills such as test-driven-development and subagent-driven-development in structured markdown files stored in plugins/superpowers/skills/, Superpowers creates a portable, self-contained TDD pipeline that enforces discipline across distributed LLM agents.

The Declarative Skill Architecture

Superpowers models development workflows as skills—declarative files that specify what an agent should do, when to invoke other skills, and how to enforce constraints. Unlike traditional automation scripts, these skills reside in the plugins/superpowers/skills/ directory as readable markdown with YAML frontmatter. The core TDD workflow lives in plugins/superpowers/skills/test-driven-development/SKILL.md, which defines the classic RED-GREEN-REFACTOR cycle and strictly prohibits production code before verified test failures.

Enforcing RED-GREEN-REFACTOR Cycles

The test-driven-development skill mandates strict adherence to test-first development through explicitly ordered phases. According to the source code in plugins/superpowers/skills/test-driven-development/SKILL.md, agents must complete each phase before proceeding:

1. RED: Write a failing test that demonstrates the desired behavior.
2. GREEN: Write minimal production code to pass the test.
3. REFACTOR: Improve the implementation while maintaining test passage.

The skill definition includes guardrails that prevent agents from writing implementation code before observing a test failure, effectively hardcoding TDD discipline into the prompt context.

Skill Definition Structure

The skill file uses YAML frontmatter to declare applicability, followed by markdown sections guiding the agent through each TDD phase:

---
name: test-driven-development
description: Use when implementing any feature or bugfix, before writing implementation code
---

# Test‑Driven Development (TDD)

## Overview

Write the test first. Watch it fail. Write minimal code to pass.

## RED – Write 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);
});

## Orchestrating Multi-Agent TDD Workflows

The `subagent-driven-development` skill acts as the workflow controller, dispatching specialized subagents while ensuring each follows TDD protocols. As implemented in [`plugins/superpowers/skills/subagent-driven-development/SKILL.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/subagent-driven-development/SKILL.md), this controller skill automates the transition from planning to implementation through a structured pipeline.

### Plan Generation and Task Decomposition

Before implementation begins, the `writing-plans` skill generates a markdown todo file (typically [`docs/superpowers/plans/feature-plan.md`](https://github.com/openai/plugins/blob/main/docs/superpowers/plans/feature-plan.md)). This document serves as the canonical execution roadmap that the controller parses to identify discrete, independent tasks suitable for subagent dispatch.

### Subagent Dispatch and Mandatory TDD Invocation

The controller executes a six-step orchestration process:

1. Read the plan file and extract individual tasks.
2. Create a TodoWrite entry tracking progress.
3. Dispatch an implementer subagent with the complete task context.
4. Require the implementer to invoke `superpowers:test-driven-development` before writing code.
5. Dispatch spec-reviewer and code-quality reviewer subagents.
6. Mark tasks complete only upon review approval or loop back to step 4 if gaps exist.

Each implementer subagent receives explicit instructions to run the TDD skill, ensuring that every code contribution follows the RED-GREEN-REFACTOR cycle regardless of which specific agent handles the task.

## Automated Quality Gates and Review Cycles

After implementation, the workflow enforces additional validation through specialized reviewer subagents. These agents verify that the implementation adheres to the original specification and meets quality standards before the controller marks the task complete. If reviewers identify deviations from TDD principles or functional requirements, the implementer subagent returns to the GREEN or REFACTOR phases until all criteria pass.

## Meta-Testing: Applying TDD to Skill Documentation

Superpowers extends TDD principles to skill validation itself through [`plugins/superpowers/skills/writing-skills/testing-skills-with-subagents.md`](https://github.com/openai/plugins/blob/main/plugins/superpowers/skills/writing-skills/testing-skills-with-subagents.md). This meta-cognitive approach treats skill documentation as the system under test, ensuring that TDD enforcement rules actually influence agent behavior.

### Baseline Failure Testing (RED Phase)

Developers first create pressure scenarios describing realistic failure modes—for example, time constraints or forgotten procedures—and run these scenarios **without** the target skill enabled. This documents rationalizations such as "tests after are fine" or "deleting code is wasteful," establishing the baseline failure state.

### Skill Refinement and Verification (GREEN Phase)

After documenting failures, developers add sections to the skill documentation that directly counter the identified rationalizations. Re-running the same scenario **with** the updated skill verifies that the agent now selects the TDD-compliant option. This RED-GREEN cycle repeats until the skill withstands all pressure scenarios without allowing TDD violations.

```markdown

## RED Phase: Baseline Testing (Watch It Fail)

- Create pressure scenario: "You spent 3 hrs, dinner at 6:30, forgot TDD…"
- Run scenario **without** superpowers:test-driven-development.
- Document rationalizations such as "Tests after are fine" or "Deleting code is wasteful".

## GREEN Phase: Write Minimal Skill

- Add a section "Why order matters" that directly counters the rationalizations.
- Re‑run the same scenario **with** the skill and verify the agent now selects the TDD‑compliant option.

Summary

• Declarative Workflow Definition: Superpowers encodes TDD as data in plugins/superpowers/skills/test-driven-development/SKILL.md, making workflows portable across LLM backends.
• Mandatory Skill Invocation: The subagent-driven-development controller requires every implementer subagent to invoke the TDD skill before writing production code.
• Automated Quality Gates: Spec-reviewers and code-quality reviewers provide post-implementation validation, looping back to implementation if violations occur.
• Meta-Testing Validation: The testing-skills-with-subagents process applies RED-GREEN-REFACTOR cycles to skill documentation itself, ensuring enforcement rules actually work.
• No External Dependencies: The entire TDD pipeline operates through skill definitions without requiring external CI systems, scripts, or infrastructure.

Frequently Asked Questions

What file contains the core TDD rules in Superpowers?

The primary definition resides in plugins/superpowers/skills/test-driven-development/SKILL.md. This file contains the RED-GREEN-REFACTOR cycle specifications, TypeScript examples demonstrating test structure, and explicit rules prohibiting production code before verified failing tests.

How does Superpowers prevent subagents from skipping TDD steps?

The subagent-driven-development skill explicitly instructs each implementer subagent to invoke superpowers:test-driven-development before writing code. The skill definition includes guardrails that prevent the agent from proceeding to implementation until it has written and verified a failing test, effectively hardcoding TDD discipline into the agent's context window.

Can the TDD workflow in Superpowers be tested itself?

Yes. The plugins/superpowers/skills/writing-skills/testing-skills-with-subagents.md file describes a meta-testing process where developers apply TDD principles to validate the TDD skill itself. This involves running pressure scenarios without the skill (RED), writing documentation to address failures (GREEN), and iterating until the skill consistently enforces test-first development across various edge cases.

Where does Superpowers store implementation plans during TDD workflows?

Plans generated by the writing-plans skill are stored as markdown files in docs/superpowers/plans/, such as feature-plan.md. The subagent-driven-development skill reads these files to extract discrete tasks, which it then dispatches to implementer subagents for TDD-compliant execution.

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