🎯

superspec-tdd

🎯Skill

from bryanhoo/superspec-skills

What it does

Mechanically enforces strict Test-Driven Development (TDD) workflow with precise rules for test verification, production code writing, and non-TDD exceptions.

📦

Part of

bryanhoo/superspec-skills(5 items)

superspec-tdd

Installation

📋 No install commands found in docs. Showing default command. Check GitHub for actual instructions.

Quick InstallInstall with npx

npx skills add bryanhoo/superspec-skills --skill superspec-tdd

Need more details? View full documentation on GitHub →

3Installs

AddedFeb 4, 2026

View on GitHub Back to Skills

Skill Details

SKILL.md

Use when executing superspec tasks to enforce strict TDD for behavior changes and allow NON-TDD exceptions only for doc/config/generated/format-only work with mechanical verification.

Overview

# Superspec TDD (Mechanical Enforcement)

Iron Law

NO PRODUCTION CODE BEFORE A VERIFIED FAILING TEST.

Task Tags

[TDD][RED]
[TDD][VERIFY_RED]
[TDD][GREEN]
[TDD][VERIFY_GREEN]
[TDD][REFACTOR]
[NON-TDD][DO]
[NON-TDD][VERIFY]

Allowed [NON-TDD] Scope (ONLY)

docs-only
config-only (no behavior change)
generated outputs
formatting/renaming only

Core Principle

If you didn't watch the test fail, you don't know if it tests the right thing.

Gates (non-negotiable)

A task line with [TDD][GREEN] MUST NOT be executed unless its corresponding [TDD][VERIFY_RED] task for the same Scenario is completed.
A [NON-TDD][DO] task MUST NOT be executed unless there is a corresponding [NON-TDD][VERIFY] task line.

VERIFY_RED Decision Table (zero-decision)

A [TDD][VERIFY_RED] task MUST result in exactly one of these outcomes:

PASS: STOP. The test is not proving missing behavior. Fix the test/spec/Test Obligation. Do not write production code.
ERROR (test runner/config/typo): STOP. Fix the error and re-run until it FAILs for the expected reason.
FAIL: Continue only if output contains the required Expected (RED) substring.

VERIFY_GREEN Decision Table (zero-decision)

A [TDD][VERIFY_GREEN] task MUST result in exactly one of these outcomes:

PASS: Continue.
FAIL: Fix production code (not the test).
Other tests failing: STOP and fix until all relevant tests are green.

REFACTOR Rule

[TDD][REFACTOR] is allowed only after [TDD][VERIFY_GREEN].
After refactor, re-run the same Verify Command and confirm it still passes.

[NON-TDD] Verification Rule

A [NON-TDD][VERIFY] step MUST be mechanical (command output / file existence / openspec validate --all --json), not a manual check.
If you cannot express verification as a command or deterministic check, this is not [NON-TDD].

When Stuck (zero-decision)

Don't know how to test: the contract is unclear. Update specs/**/spec.md Test Obligation and/or design.md Test Commands.
Test setup is huge: simplify the contract or split the Scenario.
Must mock everything: code is too coupled. Stop and revise design boundaries.

Strict Prohibitions

NEVER test mock behavior.
NEVER add test-only methods to production code.
NEVER mock without understanding dependency side effects.

Reference: references/testing-anti-patterns.md

More from this repository4

🎯

superspec-init🎯Skill

Initializes OpenSpec in the current project, setting up the superspec-rpi schema and ensuring all necessary configuration files are in place.

🎯

superspec-research🎯Skill

Researches and generates proposal and specification artifacts for a Superspec OpenSpec change using CLI commands and structured workflows.

🎯

superspec-brainstorm🎯Skill

Systematically clarifies and validates vague Superspec change requests through structured, incremental questioning and design exploration.

🎯

superspec-plan🎯Skill

Generates and updates design artifacts for OpenSpec changes by systematically inspecting status, resolving dependencies, and creating design documentation based on existing proposals and specificat...