---
name: spec-to-code-tdd
description: >-
  (💛) Spec-Driven Development meets Test-Driven Development. Takes any SPEC.md generated by respec
  (speck) and orchestrates implementation in a dedicated repository/workspace using a strict RED ->
  GREEN -> REFACTOR cycle.
compatibility: Gemini CLI, Antigravity, Claude Code
metadata:
  version: 0.1.0
---

# 💛 Spec-to-Code TDD — From `SPEC.md` to Verified Implementation

> *"Specs are the durable artifact; code is increasingly just a rendering of them."*
> — Re-SPEC philosophy

This skill bridges the gap between a **Specification** (such as one generated by `respec` / `speck`) and a **Working Implementation**, using rigorous Test-Driven Development (TDD) while preventing repository boundary violations.

---

## 🛑 Rule 0: The Foundry Isolation Principle

**NEVER implement the app or game inside the `respec` repository itself!**
- `respec` is the **Spec Foundry**: it only produces and holds `SPEC.md`, `input_prompt.md`, notes, and concept assets.
- All actual code (engines, servers, frontend, CLI binaries of the specified tool) **MUST live in a dedicated repository** or an isolated external workspace (e.g. `~/git/<project-slug>/` or a dedicated worktree/sandbox).

If you are currently inside `respec`, HALT implementation and ask the user to switch to or initialize the target repository before writing code!

---

## The 4-Phase Execution Cycle

```
+-----------------------------------------------------------------+
|                    SPEC-TO-CODE TDD LIFECYCLE                   |
|                                                                 |
|   1. SPEC Ingestion & Criteria Extraction                       |
|         v                                                       |
|   2. Phase RED: Author Acceptance Tests (Must FAIL initially)   |
|         v                                                       |
|   3. Phase GREEN: Minimal Clean Implementation (Pass Tests)     |
|         v                                                       |
|   4. Phase REFACTOR & Drift Audit: Verify Against SPEC.md       |
+-----------------------------------------------------------------+
```

### Phase 1: Ingestion & Acceptance Criteria Mapping
1. Read the input `SPEC.md` thoroughly (including any user stories, data models, edge cases, and success metrics).
2. Decompose the spec into a prioritized checklist of testable capabilities:
   - **Core State & Data Models** (e.g. Tile rotation, Board representation, Entities).
   - **Game/Business Rules** (e.g. Win/Loss conditions, valid moves, constraints).
   - **Edge Cases & Error Handling** (e.g. loops, boundaries, unexpected inputs).
3. Confirm the tech stack and test runner in the target repository (e.g. `go test`, `pytest`, `vitest`).

### Phase 2: Phase RED (Test-First)
1. Write unit and integration tests strictly based on the Acceptance Criteria extracted in Phase 1.
2. Follow these testing rules:
   - **Test behavior, not implementation details**: Assert on public outputs and state transitions, not internal private helpers.
   - **Deterministic & Isolated**: Each test must execute independently without lingering state.
   - **Real logic over excessive mocks**: Use in-memory data structures or lightweight test fixtures.
3. **Execute the test runner and verify tests FAIL (RED)**:
   - Ensure the failure is due to missing feature logic, *not* a compilation/syntax error or bad import.

### Phase 3: Phase GREEN (Defensive Implementation)
1. Write the minimal clean production code necessary to make the failing tests pass.
2. Adhere to design patterns suited for the domain (e.g. `niccolo-game-design` manager patterns for games, or modular interfaces for CLIs/libraries).
3. Run the test suite:
   - Confirm all tests pass cleanly (**GREEN**).

### Phase 4: Phase REFACTOR & Drift Audit
1. Refactor and eliminate duplication while keeping tests 100% green.
2. **Drift Audit**: Compare the resulting implementation with `SPEC.md`:
   - Did the implementation reveal ambiguities in the spec?
   - Did any requirement change during development?
3. **Drift Reconciliation**: If drift is observed, alert the user and propose a concise 1-2 line clarification to the original `SPEC.md` in the spec foundry.