TDD Implementation Skill

TDD Implementation

Implement code changes using the Test-Driven Development (RED/GREEN/REFACTOR) cycle. This skill defines the complete workflow from task metadata validation through atomic commit.

Task Metadata

Each task you work on must have the following in its metadata:

{
  "plan": "<plan-name>",
  "type": "spike|bug|task|epic|story",
  "acceptance_criteria": ["..."],
  "relevant_documentation": "",
  "testing_requirements": ["..."],
  "skills": ["..."],
  "learnings": ["..."],
  "verification": {
    "type": "test|ui-recording|test-coverage|api-test|manual-check|documentation",
    "command": "the proof command",
    "expected": "what success looks like"
  }
}

All fields are mandatory — empty arrays are ok. If any are missing, ask the agent team to fill them in and wait to get a response.

Workflow

Verify task metadata — All fields are mandatory. If any are missing, ask the agent team to fill them in and wait to get a response.
Load skills — Load the skills in the skills property of the task metadata.
Read before writing — Read existing code before modifying it. Understand acceptance criteria, verification, and relevant research.
Follow existing patterns — Match the style, naming, and structure of surrounding code.
One task at a time — Complete the current task before moving on.
RED — Write a failing test that captures the expected behavior from the task description. Focus on testing behavior, not implementation details.
GREEN — Write the minimum production code to make the test pass.
REFACTOR — Clean up while keeping tests green.
Verify empirically — Run the task's proof command and confirm expected output.
Update documentation — Add/Remove/Modify all relevant JSDoc preambles, explaining "why", not "what".
Update the learnings — Add what you learned during implementation to the learnings array in the task's metadata.learnings. These should be things that are relevant for other implementers to know.
Commit atomically — Once verified, run the /git-commit skill.

TDD Cycle

Always write failing tests before implementation code. This is mandatory, not optional.

TDD Cycle:
1. RED: Write a failing test that defines expected behavior
2. GREEN: Write the minimum code to make the test pass
3. REFACTOR: Clean up while keeping tests green

RED Phase

Write a test that captures the expected behavior from the task description
Focus on testing behavior, not implementation details
The test must fail before you write any production code
If the imported module doesn't exist, Jest reports 0 tests found (not N failed) — this is expected RED behavior

GREEN Phase

Write the minimum production code to make the test pass
Do not optimize, do not add features beyond what the test requires
The goal is the simplest code that makes the test green

REFACTOR Phase

Clean up code while keeping all tests green
Remove duplication, improve naming, simplify structure
Run tests after every refactor step to confirm nothing breaks

When Stuck

Re-read the task description and acceptance criteria
Check relevant research for reusable code references
Search the codebase for similar implementations
Ask the team lead if the task is ambiguous — do not guess

Agent Skills: TDD Implementation

Install this agent skill to your local

Skill Files