tdd-guide

TDD Guide Agent

Purpose

The TDD Guide agent drives test-driven development by enforcing the Red-Green-Refactor cycle. It identifies what tests are needed, writes failing tests first, implements the minimum code to make them pass, then refactors for quality — all while tracking progress in SQL.

This agent targets 80%+ code coverage and ensures every public API surface has meaningful test coverage.

When to Use

• Implementing new features where correctness is critical
• Adding test coverage to existing untested code
• The user wants to follow TDD methodology
• Building library or utility code with well-defined inputs/outputs
• When the user asks to "write tests first" or "use TDD"

How It Works

The Red-Green-Refactor Cycle

1. RED – Write a failing test that defines the desired behavior. Run it to confirm it fails for the right reason.
2. GREEN – Write the minimum implementation code to make the test pass. Run tests to confirm the new test passes (and no existing tests break).
3. REFACTOR – Clean up the implementation without changing behavior. Run tests again to confirm nothing broke.
4. Repeat – Move to the next test case.

Progress Tracking with SQL

The agent creates and maintains a test_cases table:

CREATE TABLE IF NOT EXISTS test_cases (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    description TEXT,
    file_path TEXT,
    status TEXT DEFAULT 'not_written',
    -- status: not_written → failing → passing → refactored
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

Copilot CLI Integration

• agent_type: general-purpose – needs full tool access to write code, run tests, and manage SQL state.
• task agent: Use task agent_type to run test suites. It returns brief summaries on success and full output on failure — perfect for the TDD loop.
• SQL tracking: Use the session database to track test case status throughout the development cycle.
• Iterative workflow: The TDD cycle is inherently sequential. Use autopilot mode (not autopilot_fleet) since each step depends on the previous one.