tdd-workflow

TDD Workflow

Test-Driven Development (TDD) workflow for tasks marked with approach: "tdd".

CRITICAL: TDD tasks MUST follow this exact sequence. Gate hooks will block out-of-order operations.

---

Scoped vs Full Test Execution

During TDD phases (RED/GREEN/REFACTOR):

• Run scoped tests only (specific test file or pattern)
• Fast feedback loop for the feature being developed
• Full test suite is deferred to VERIFY task

During VERIFICATION phase:

• Verifier runs full test suite (npm test without scope)
• Ensures no regressions across entire codebase
• PASS/FAIL determination based on complete test coverage

Why scoped execution?

1. Speed: Test only what changed, not entire suite
2. Focus: TDD cycle targets specific behavior
3. Separation: Task implementation vs system verification

Using test_scope from Task

When task has test_scope field, use it for scoped execution:

# Read test_scope from task
TEST_SCOPE=$(bun "{SCRIPTS_PATH}/task-get.js" --session ${CLAUDE_SESSION_ID} --id {TASK_ID} --field test_scope)

# Run scoped test
npm test -- {test_scope}

Example task.json:

{
  "id": "3",
  "subject": "Add input validation",
  "approach": "tdd",
  "test_scope": "tests/validation.test.ts"
}

If test_scope is not set, use the test file path you created.

---

TDD Phase 1: RED - Write Failing Test

1. Create test file FIRST (before any implementation code)
2. Write test for expected behavior
3. Run test and VERIFY IT FAILS

# Record test creation
bun "{SCRIPTS_PATH}/task-update.js" --session ${CLAUDE_SESSION_ID} --id {TASK_ID} \
  --add-evidence "TDD-RED: Created test file tests/validateUser.test.ts"

# Run SCOPED test - MUST FAIL
npm test -- tests/validateUser.test.ts

# Record failure (expected)
bun "{SCRIPTS_PATH}/task-update.js" --session ${CLAUDE_SESSION_ID} --id {TASK_ID} \
  --add-evidence "TDD-RED: npm test -- tests/validateUser.test.ts (exit code 1)"

Evidence Required:

• Test file path created
• Scoped test execution output showing failure
• Exit code 1 (expected)
• Evidence includes full test command with scope