---
name: tdd-executor
description: >-
  Runs red/green/refactor loops against acceptance criteria and TEST_STRATEGY. Use when practicing TDD or when tests should lead implementation. Emits TDD_SESSION. Never skips red, never refactors on red, never claims green without command evidence.
version: 2.0.0
author: Will Silveira
---

# Purpose

Implement behavior test-first with a disciplined red → green → refactor loop tied to AC IDs.

# When to Use / When NOT to Use

**Use when:** user asks for TDD; high-correctness units; pairing with TEST_STRATEGY; implementing pure logic/API contracts.

**Do not use when:** spike/prototype explicitly throwaway; pure docs; exploratory defect triage (defect-analyst first).

# Preconditions

At least one testable AC or behavior statement. Prefer TEST_STRATEGY + TASK_GRAPH. Project test command discoverable.

# Inputs / Outputs

**Inputs:** AC IDs, TEST_STRATEGY, CONTEXT_PACK, task scope.

**Outputs:** `TDD_SESSION` (+ code/tests); may produce/update IMPL_REPORT fields.

# Upstream / Downstream

**Upstream:** test-strategy-designer, delivery-planner, spec-validator.

**Downstream:** feature-implementer (if continuing), code-reviewer, quality-gate.

# Core Principles

1. Red before implementation for the vertical under test.
2. Green: minimal code to pass.
3. Refactor only on green; keep tests green.
4. One failing behavior at a time.
5. Behavior-focused tests; avoid testing privates unless necessary.
6. Record exact commands and outcomes.
7. Stop if AC is untestable — hand back to spec-validator.

# Process

For each AC/slice:
1. **Red** — write failing test; run; capture failure.
2. **Green** — minimal implementation; run; capture pass.
3. **Refactor** — clean structure; run; stay green.
4. Update TDD_SESSION log per cycle.
5. After cycles, summarize coverage vs AC IDs; note gaps.

## Lite
Single function/bugfix: one red/green cycle + optional refactor.

# Evidence Requirements

commands_run with fail then pass. No “should pass” without running.

# Stop Conditions / Failure Modes

| Condition | Action |
|-----------|--------|
| Cannot get a failing test (already green) | Revisit AC / test design |
| Untestable AC | Hand off spec-validator |
| Refactor breaks tests | Fix before continuing |

# Severity + Confidence

N/A primarily; residual risk if ACs unverified.

# Output Contract

```
## TDD_SESSION
AC focus: ...
Cycles:
  - red: command/result
  - green: command/result
  - refactor: command/result
Remaining gaps: ...
Decision: Proceed | ProceedWithConditions | Revise | Block
```

# Handoffs

**feature-implementer** (broader wiring), **code-reviewer**, **spec-validator**, **test-strategy-designer**.

# Never

- Never write implementation before a failing test in TDD mode (unless user aborts TDD).
- Never refactor on red.
- Never invent green test results.