spec-to-code-tdd

# 💛 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.