/tdd-cycle

description: Execute full TDD red-green-refactor cycle with validation gates. Use when saying "TDD cycle", "test-driven development", or "full TDD workflow".
version: 1.0.0

TDD Cycle - Comprehensive Test-Driven Development

--phase Flag (v1.1.0+)

`sw:tdd-cycle` supports a `--phase` flag to run a single phase of the RED → GREEN → REFACTOR cycle. Omitting the flag (or passing `--phase all`) runs the full cycle.

| Flag | Behavior | |------|----------| | `--phase all` (default) | Full RED → GREEN → REFACTOR cycle. Same as omitting the flag. | | `--phase red` | Runs only the RED phase — write failing tests. See Phase 2 below. | | `--phase green` | Runs only the GREEN phase — write minimal code to make tests pass. See Phase 3 below. | | `--phase refactor` | Runs only the REFACTOR phase — improve code quality with tests as safety net. See Phase 4 below. |

Alias routing from deprecated skills

The following deprecated single-phase skills are aliased in `marketplace.json` to route through `sw:tdd-cycle --phase <x>`:

• `/sw:tdd-red` → `/sw:tdd-cycle --phase red`
• `/sw:tdd-green` → `/sw:tdd-cycle --phase green`
• `/sw:tdd-refactor` → `/sw:tdd-cycle --phase refactor`

The aliases emit a one-time migration warning pointing users to the canonical `--phase` form. The three `tdd-*` skills are scheduled for removal in v1.3.0 — see `.specweave/docs/internal/specs/skill-deprecation-policy.md`.

Examples

# Full cycle (default)
sw:tdd-cycle "user authentication"

# Single phases
sw:tdd-cycle --phase red "user authentication"
sw:tdd-cycle --phase green "user authentication"
sw:tdd-cycle --phase refactor "user authentication"

# Same as default — explicit
sw:tdd-cycle --phase all "user authentication"

---

Project Overrides

**Skill Memories**: If `.specweave/skill-memories/tdd-cycle.md` exists, read and apply its learnings.

Execute a comprehensive Test-Driven Development (TDD) workflow with strict red-green-refactor discipline:

[Extended thinking: This workflow enforces test-first development through coordinated agent orchestration. Each phase of the TDD cycle is strictly enforced with fail-first verification, incremental implementation, and continuous refactoring. The workflow supports both single test and test suite approaches with configurable coverage thresholds.]

Configuration

Coverage Thresholds

• Minimum line coverage: 80%
• Minimum branch coverage: 75%
• Critical path coverage: 100%

Refactoring Triggers

• Cyclomatic complexity > 10
• Method length > 20 lines
• Class length > 200 lines
• Duplicate code blocks > 3 lines

Phase 1: Test Specification and Design

1. Requirements Analysis

• Use Task tool with subagent_type="Plan"
• Prompt: "Analyze requirements for: $ARGUMENTS. Define acceptance criteria, identify edge cases, and create test scenarios. Output a comprehensive test specification."
• Output: Test specification, acceptance criteria, edge case matrix
• Validation: Ensure all requirements have corresponding test scenarios

2. Test Architecture Design

• Use Task tool with subagent_type="general-purpose"
• Prompt: "Design test architecture for: $ARGUMENTS based on test specification. Define test structure, fixtures, mocks, and test data strategy. Ensure testability and maintainability."
• Output: Test architecture, fixture design, mock strategy
• Validation: Architecture supports isolated, fast, reliable tests

Phase 2: RED - Write Failing Tests

3. Write Unit Tests (Failing)

• Use Task tool with subagent_type="general-purpose"
• Prompt: "Write FAILING unit tests for: $ARGUMENTS. Tests must fail initially. Include edge cases, error scenarios, and happy paths. DO NOT implement production code."
• Output: Failing unit tests, test documentation
• **CRITICAL**: Verify all tests fail with expected error messages

4. Verify Test Failure

• Use Task tool with subagent_type="general-purpose"
• Prompt: "Verify that all tests for: $ARGUMENTS are failing correctly. Ensure failures are for the right reasons (missing implementation, not test errors). Confirm no false positives."
• Output: Test failure verification report
• **GATE**: Do not proceed until all tests fail appropriately

Phase 3: GREEN - Make Tests Pass

5. Minimal Implementation

• Use Task tool with subagent_type="general-purpose"
• Prompt: "Implement MINIMAL code to make tests pass for: $ARGUMENTS. Focus only on making tests green. Do not add extra features or optimizations. Keep it simple."
• Output: Minimal working implementation
• Constraint: No code beyond what's needed to pass tests

6. Verify Test Success

• Use Task tool with subagent_type="general-purpose"
• Prompt: "Run all tests for: $ARGUMENTS and verify they pass. Check test coverage metrics. Ensure no tests were accidentally broken."
• Output: Test execution report, coverage metrics
• **GATE**: All tests must pass before proceeding

Phase 4: REFACTOR - Improve Code Quality

7. Code Refactoring

• Use Task tool with subagent_type="general-purpose"
• Prompt: "Refactor implementation for: $ARGUMENTS while keeping tests green. Apply SOLID principles, remove duplication, improve naming, and optimize performance. Run tests after each refactoring."
• Output: Refactored code, refactoring report
• Constraint: Tests must remain green throughout

8. Test Refactoring

• Use Task tool with subagent_type="general-purpose"
• Prompt: "Refactor tests for: $ARGUMENTS. Remove test duplication, improve test names, extract common fixtures, and enhance test readability. Ensure tests still provide same coverage."
• Output: Refactored tests, improved test structure
• Validation: Coverage metrics unchanged or improved

Phase 5: Integration and System Tests

9. Write Integration Tests (Failing First)

• Use Task tool with subagent_type="general-purpose"
• Prompt: "Write FAILING integration tests for: $ARGUMENTS. Test component interactions, API contracts, and data flow. Tests must fail initially."
• Output