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

---

TDD Phase 2: GREEN - Minimal Implementation

1. Write MINIMAL code to make the test pass
2. Do NOT add extra functionality beyond what test requires
3. Run test and VERIFY IT PASSES

# Record implementation
bun "{SCRIPTS_PATH}/task-update.js" --session ${CLAUDE_SESSION_ID} --id {TASK_ID} \
  --add-evidence "TDD-GREEN: Implemented src/validateUser.ts"

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

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

Evidence Required:

• Implementation file path
• Scoped test execution output showing pass
• Exit code 0
• Evidence includes full test command with scope

---

TDD Phase 3: REFACTOR (Optional)

1. Improve code quality (naming, structure, performance)
2. Run scoped tests again to ensure they still pass
3. Record any refactoring done

# Run SCOPED test after refactoring
npm test -- tests/validateUser.test.ts

# Record refactoring
bun "{SCRIPTS_PATH}/task-update.js" --session ${CLAUDE_SESSION_ID} --id {TASK_ID} \
  --add-evidence "TDD-REFACTOR: Renamed variables, npm test -- tests/validateUser.test.ts (exit code 0)"

---

TDD Evidence Chain

A complete TDD task MUST have this evidence sequence:

1. TDD-RED: Test file created
2. TDD-RED: Scoped test execution failed (exit code 1, includes test scope)
3. TDD-GREEN: Implementation created
4. TDD-GREEN: Scoped test execution passed (exit code 0, includes test scope)
5. (Optional) TDD-REFACTOR: Improvements made, scoped tests still pass

Evidence format MUST include:

• Full test command with scope (e.g., npm test -- tests/feature.test.ts)
• Exit code in parentheses
• Phase prefix (TDD-RED, TDD-GREEN, TDD-REFACTOR)

Verification will FAIL if:

• Implementation evidence appears before TDD-RED evidence
• Missing TDD-RED or TDD-GREEN evidence
• Test never failed (suggests code-first, not test-first)
• Evidence missing test scope or exit code

---

Gate Enforcement

The gate-enforcement.js hook blocks out-of-order TDD operations:

During EXECUTION phase (TDD tasks only):

• ✅ Allow: Test files first (*.test.*, *.spec.*, __tests__/*)
• ❌ Block: Implementation files before TDD-RED evidence

Detection Logic:

1. Hook reads task file to check approach: "tdd"
2. Searches evidence array for "TDD-RED" prefix
3. If TDD task + no RED evidence → blocks Write/Edit on non-test files

Error Message:

TDD gate: Cannot write implementation before RED phase
Required evidence: "TDD-RED: Test fails as expected (exit code 1)"
Current file: src/validateUser.ts (non-test file)

---

TDD Task Completion

After all phases complete:

bun "{SCRIPTS_PATH}/task-update.js" --session ${CLAUDE_SESSION_ID} --id {TASK_ID} \
  --status resolved \
  --add-evidence "TDD complete: RED→GREEN→REFACTOR cycle finished"

---

Quick Reference

Phase	Action	Evidence Prefix	Exit Code
RED	Write test, verify failure	TDD-RED: ...	1 (fail)
GREEN	Write minimal impl, verify pass	TDD-GREEN: ...	0 (pass)
REFACTOR	Improve code, tests still pass	TDD-REFACTOR: ...	0 (pass)

---

Example Evidence Sequence

{
  "evidence": [
    "TDD-RED: Created test file tests/auth.test.ts",
    "TDD-RED: npm test -- tests/auth.test.ts (exit code 1)",
    "TDD-GREEN: Implemented src/auth.ts",
    "TDD-GREEN: npm test -- tests/auth.test.ts (exit code 0)",
    "TDD-REFACTOR: Extracted helper, npm test -- tests/auth.test.ts (exit code 0)"
  ]
}

Note: Full test suite (npm test without scope) is run only during VERIFICATION phase by the verifier agent.