TDD Workflow

This skill defines the test-driven development workflow for implementing one acceptance criterion. All TDD agents share this mental model.

Cycle Overview

RED → GREEN → REVIEW → REFACTOR

Human approval required before each phase transition.

Entry Point

This workflow receives one acceptance criterion (AC) to implement. The AC should be:

• Specific and testable
• Small enough for one TDD cycle
• Approved by human before starting

Phase Details

RED: Write Failing Tests

Agent: TestAgent

Actions:

1. Analyze the acceptance criterion
2. Write test cases (happy path, edge cases, errors)
3. Run tests — confirm failure
4. Stop and report

Rules:

• No mock implementations
• No guessing — ask human if ambiguous
• Tests are executable specifications

Exit: Human approves tests → proceed to GREEN

GREEN: Write Passing Code

Agent: ImplementationAgent

Actions:

1. Read failing tests
2. Write minimum code to pass
3. Run tests after each change
4. Iterate until green
5. Stop and report

Rules:

• Never modify tests
• Never add untested functionality
• Suggest test additions if edge cases spotted
• When unsure about library usage, use context7 mcp tool

Exit: Human approves implementation → proceed to REVIEW

REVIEW: Verify Implementation

Agent: ReviewAgent

Actions:

1. Read tests independently
2. Read implementation independently
3. Check for overfitting, gaps, flaws
4. Report findings

Rules:

• Never modify code
• Be skeptical — assume overfitting until proven otherwise
• Provide specific, actionable feedback

Exit: PASS → proceed to REFACTOR. CONCERNS → human decides next step.

REFACTOR: Clean Code

Agent: RefactorAgent

Actions:

1. Confirm green baseline
2. One refactoring at a time
3. Run tests after each change
4. Run linter and formatter
5. Stop and report

Rules:

• Never change behavior
• Revert immediately if tests go red
• SOLID principles non-negotiable
• Minimal comments — clean code is documentation

Exit: Human approves refactoring → TDD cycle complete

Exit Point

When REFACTOR phase completes:

• Tests pass
• Code reviewed
• Code clean
• Ready for commit (handled by outer workflow)

Tooling Detection

Agents auto-detect project tooling when explicit instructions absent:

If detection fails, ask human for explicit instructions.

Context Preservation

TDD Context File

.tdd_context.md tracks state within this TDD cycle:

# TDD Cycle Context

**Acceptance Criterion**: User can log in with email and password
**Started**: 2026-01-29 10:15
**Current Phase**: GREEN

## Phases Completed

- [x] RED (2026-01-29 10:20)

## Key Decisions

- Chose vitest over jest due to existing `vitest.config.ts`
- JWT validation will use RS256 algorithm

## Errors Encountered

### Phase: RED
**Error**: Import path resolution failed for `@/lib/auth`
**Resolution**: Updated `tsconfig.json` paths mapping

## Files Modified

- `test/auth.test.ts` — Added authentication test cases
- `src/auth.ts` — Placeholder created for implementation

## Next Agent Notes

**For ImplementationAgent**:
- Tests expect JWT token validation with RS256
- Must handle both valid and expired tokens

Rules:

• Create at cycle start
• Update after each phase
• Each agent reads this file first
• Append-only during cycle — never delete previous phase notes

Micro-Edit Protocol

All agents follow this pattern:

1. Make one small, logical change
2. Run relevant checks (tests, lint, etc.)
3. Stop and report to human
4. Wait for approval before continuing

This keeps changes reviewable and reversible.

Quality Standards

Code Style (Uncle Bob principles)

• Expressive names over comments
• Single responsibility per function/class
• Small functions (< 20 lines preferred)
• No dead code
• DRY — extract when pattern repeats 3+ times
• Early returns over deep nesting
• Strict TypeScript — no any

Test Style

• Descriptive names: should_reject_expired_token not test1
• One assertion concept per test
• Arrange-Act-Assert structure
• Real assertions over excessive mocking
• Tests document behavior

Anti-Patterns

Agents must avoid:

• Compliments, praise, or flattery
• Guessing when requirements unclear
• Large changes without checkpoints
• Modifying code outside their phase responsibility
• Over-explaining — human knows the workflow
• Starting work without reading .tdd_context.md
• Skipping phases or combining multiple ACs