--- name: "tdd-workflow" description: "Enforces strict Red-Green-Refactor TDD cycle. Tests first, minimal implementation, then refactor. Inspired by obra/superpowers and Aider architect mode." metadata: version: "1.0.0" --- # TDD Workflow > **Purpose:** Enforce a strict Red-Green-Refactor test-driven development cycle. The agent writes tests FIRST, then implements just enough code to make them pass, then refactors. --- ## Invocation ``` /tdd ``` --- ## The Cycle ### Phase 1: RED — Write Failing Tests 1. Create a test file (or add to existing) 2. Write test cases that describe the desired behavior 3. Run the test suite — confirm tests FAIL 4. **Do NOT write any implementation yet** ```bash $ npx vitest run src/utils/slug.test.ts FAIL src/utils/slug.test.ts ✗ converts spaces to hyphens ✗ lowercases all characters ✗ removes special characters ✗ handles empty string ``` ### Phase 2: GREEN — Write Minimum Implementation 1. Write the simplest code that makes ALL tests pass 2. No extra features, no optimization, no "while I'm here" additions 3. Run tests — confirm they PASS ```bash $ npx vitest run src/utils/slug.test.ts ✓ src/utils/slug.test.ts (4 tests) ✓ converts spaces to hyphens ✓ lowercases all characters ✓ removes special characters ✓ handles empty string ``` ### Phase 3: REFACTOR — Clean Up 1. Improve code quality WITHOUT changing behavior 2. Run tests after each refactor step — they must stay GREEN 3. Look for: duplication, unclear naming, complex conditionals, missing types 4. Commit when satisfied --- ## Rules 1. **Never write implementation before tests** — If you catch yourself coding logic before a test exists, stop and write the test first. 2. **One test at a time** — Write one test, see it fail, make it pass. Then the next. 3. **Minimal implementation** — Don't write code "you'll need later." Only satisfy current tests. 4. **Tests must fail first** — If a new test passes immediately, either the test is wrong or the behavior already exists. Investigate. 5. **Refactor only when green** — Never refactor while tests are failing. 6. **Small commits** — Commit at the end of each RED-GREEN-REFACTOR cycle. --- ## Commit Convention ``` test: add tests for slug utility (RED) feat(utils): implement slug generation (GREEN) refactor(utils): simplify slug regex (REFACTOR) ``` --- ## When to Break the Cycle It's okay to skip TDD for: - Configuration files (no logic to test) - Type definitions (TypeScript compiler is the test) - One-line wrappers around well-tested libraries - UI layout (visual testing is better here) But ALWAYS use TDD for: - Business logic - Data transformations - Validation rules - API endpoint handlers - State management logic ## Playground
TDD Workflow · Red→Green→Refactor
🔴 RED
Write a failing test.
Run it. See it fail.
→
🟢 GREEN
Write minimum code
to pass the test.
→
🔵 REFACTOR
Clean up. Keep tests
green. Repeat.
Rule: never write production code without a failing test first.
Rule: commit after each green. CI must stay green at every commit.