tdd-workflow

# TDD Workflow ## Core Principle **Never write implementation code before a failing test exists for that behavior.** ## Execution Flow ### 1. Setup ``` LANG = config_read("tech_stack", "unknown") If LANG == "unknown": detect from project files (package.json → TypeScript, Gemfile → Ruby, go.mod → Go, pyproject.toml → Python) If LANG == "unknown": AskUserQuestion("What language/framework?") RUNNER = lookup LANG in [references/language-configs.md] If LANG in [ruby]: delegate to `rspec-coder` or `minitest-coder` skill for runner details INCREMENTS = decompose feature using patterns from [references/increments.md] - Read requirements/plan - Identify pattern (Data Transformation, CRUD, State Machine, Calculation, Integration) - Break into ordered increments: degenerate → happy path → variations → edge cases → errors For each INCREMENT in INCREMENTS: TaskCreate(subject: INCREMENT.name, description: INCREMENT.test_description) AskUserQuestion("Review increments. Adjust ordering or scope?", options: ["Looks good", "Modify"]) ``` ### 2. TDD Loop (per increment) ``` For each INCREMENT in INCREMENTS: TaskUpdate(INCREMENT.task_id, status: "in_progress") # RED Write failing test to real file (not code block) RUN = Bash(RUNNER.test_command) If RUN.status == PASS: STOP — investigate unexpected pass If RUN.status == FAIL (wrong reason): fix test, rerun PAUSE → show test + failure output, wait for user # GREEN Write minimal implementation code RUN = Bash(RUNNER.full_suite_command) If RUN.status == FAIL: show output, PAUSE → ask user to fix or hand off If RUN.status == PASS: auto-continue (no pause) # REFACTOR If improvement opportunities exist: Refactor implementation and/or test code RUN = Bash(RUNNER.full_suite_command) If RUN.status == FAIL: revert refactor, PAUSE → discuss If RUN.status == PASS: auto-continue (no pause) TaskUpdate(INCREMENT.task_id, status: "completed") Brief summary of what was implemented → immediately begin next increment (no pause between increments) ``` ### 3. Wrap-up ``` RUN = Bash(RUNNER.full_suite_command) Report: increments completed, total tests, pass/fail status Suggest: remaining work, missed edge cases, integration tests needed ``` ## Pause/Continue Rules | Situation | Action | |-----------|--------| | RED: test fails (expected) | **Pause** — show test + failure, wait for user | | RED: test passes unexpectedly | **Stop** — investigate, don't proceed | | GREEN: all tests pass | **Auto-continue** to REFACTOR | | GREEN: tests fail | **Pause** — show output, ask user | | REFACTOR: tests pass | **Auto-continue** to next increment | | REFACTOR: tests fail | **Revert + Pause** — discuss approach | | Between increments | **Auto-continue** — no pause | ## Task Tracking Integration ``` TASK_TRACKING = config_read("task_tracking.enabled", "false") WORKFLOW_ID = "tdd-{timestamp}" If TASK_TRACKING: For each TaskCreate: add metadata {workflow: WORKFLOW_ID, phase: "tdd-loop"} For each TaskUpdate: wrap with If TASK_TRACKING: TaskUpdate(...) On Wrap-up: update ledger if LEDGER_ENABLED LEDGER_ENABLED = config_read("task_tracking.ledger", "false") LEDGER_PATH = config_read("task_tracking.ledger_path", ".agents/workflow-ledger.yml") ``` ## Red-Green-Refactor Cycle ### 1. Red Phase: Write a Failing Test - Select one small, specific behavior from the increment - Write a descriptive test that expresses the expected behavior - Run the test to confirm it **fails** (red) - The failure should be for the right reason (not syntax error or missing dependency) ### 2. Green Phase: Minimal Implementation - Implement only the minimal code necessary to pass the failing test - Resist adding extra features or handling edge cases not yet covered by tests - Run the test to confirm it **passes** (green) ### 3. Refactor Phase: Improve Quality - Review both implementation and test code for improvements - Remove duplication, improve naming, extract methods - Apply language-specific idioms and patterns - Run tests after each refactoring step to ensure they still **pass** ## Test Sequencing Strategy **Order tests from simple to complex:** 1. **Happy path** — The core behavior with valid inputs 2. **Validation tests** — Required fields, format constraints 3. **Edge cases** — Boundary conditions, empty values, unusual inputs 4. **Error handling** — Invalid inputs, failure scenarios 5. **Integration points** — Interactions with other components ## Test Quality Guidelines **Each test should:** - Cover exactly one behavior - Be isolated — no shared state between tests - Have a clear, descriptive name - Fail for only one reason **Avoid:** - Testing implementation details instead of behavior - Writing tests after the code - Sharing test setup that creates hidden dependencies - Skipping the refactor phase ## Framework-Specific Implementation For language-specific test runner commands, see [references/language-configs.md](references/language-configs.md). For Ruby projects: - **RSpec:** Apply `rspec-coder` skill - **Minitest:** Apply `minitest-coder` skill A Rails example is available in [references/rails-tdd-workflow.md](references/rails-tdd-workflow.md). ## Test Generation Patterns When writing tests outside a TDD loop (e.g., adding coverage to existing code), follow these patterns. ### Framework Detection | Evidence | Framework | |----------|-----------| | `spec/` + `_spec.rb` + `.rspec` | RSpec | | `test/` + `_test.rb` + `test_helper.rb` | Minitest | | `*.test.js` + `jest.config.js` | Jest | | `*.spec.ts` in `tests/` or `e2e/` | Playwright | | `vitest.config.js` | Vitest | ### Test Plan Structure Before writing tests, create a plan covering: 1. **Scope** - What functionality will be tested 2. **Happy path scenarios** - Expected successful flows 3. **Sad path scenarios** - Error handling, validations, failures 4. **Edge cases** - Boundary conditions, null/empty values, unusual inputs 5. **Auth checks** - Authorization/authentication (if applicable) 6. **Test data requirements** - Fixtures or data needed 7. **Mocking strategy** - External services/dependencies to mock ### Test Case Matrix Use for complex scenarios with multiple parameters: | Objective | Inputs | Expected Output | Test Type | |-----------|--------|-----------------|-----------| | Validate creation | valid params | Created, 201 | Happy Path | | Reject duplicate | existing data | Error, 422 | Sad Path | | Handle empty | missing field | Validation error | Edge Case | ### Completion Criteria Tests are complete when ALL of these are met: **Coverage:** All public methods tested, happy/sad/edge paths covered, auth checks included. **Quality:** Tests pass (verified by running), isolated (no shared state), follow AAA pattern (Arrange-Act-Assert), descriptive names. **Framework compliance:** Proper matchers, appropriate mocking, follows project patterns. ### Test Writing Best Practices - Test behavior, not implementation details - One assertion focus per test - Use descriptive test names that document expected behavior - Prefer explicit assertions over implicit ones - Use test doubles sparingly and purposefully - Group related tests with describe/context blocks - Test data should be minimal but sufficient - For Rails: use transactional fixtures and database cleaner - For Playwright: proper waiting strategies, avoid flaky selectors