How the TDD Guide Agent Facilitates Iterative Workflows in Claude Code

The TDD guide agent drives a disciplined RED → GREEN → REFACTOR cycle by scaffolding interfaces first, generating failing tests, providing minimal implementations, and enforcing continuous verification through automated test runs and coverage checks.

The tdd-guide agent in the WorldFlowAI/everything-claude-code repository is a purpose-built Test-Driven Development specialist that transforms how developers approach incremental code changes. Unlike generic coding assistants, this agent embeds the TDD philosophy directly into its operational loop, ensuring every feature begins with verification and ends with validated, clean code. This article examines how the agent orchestrates iterative workflows through its command structure and automated checkpoints.

The Core TDD Loop: RED → GREEN → REFACTOR

The TDD guide agent implements the classic TDD cycle as a repeatable, automated workflow. Each iteration follows seven precise steps that guarantee test-first development.

Step 1: Scaffold Interfaces First

Before any logic exists, the agent writes TypeScript type definitions that establish clear contracts for inputs and outputs. This creates an unambiguous specification that both the test and implementation will obey.

Step 2: Generate Failing Tests (RED)

The agent emits a complete test suite that deliberately fails because no implementation exists. This confirms the test is actually testing something meaningful—not merely passing vacuously.

Step 3: Run and Confirm Failure

The agent invokes npm test and verifies that the new tests fail as expected. This validates the test-first premise: the test must be capable of detecting missing or incorrect behavior.

Step 4: Minimal Implementation (GREEN)

Only the code required to make the failing test pass is added. The agent keeps the change surface small and focused, resisting the temptation to over-engineer.

Step 5: Verify Green State

The test suite is re-executed to confirm the new code satisfies expectations. This closes the RED → GREEN transition.

Step 6: Refactor Safely (REFACTOR)

Once green, the agent suggests clean-up steps—extracting constants, improving naming, reducing duplication—while continuously re-checking that tests stay green.

Step 7: Enforce Coverage Threshold

The agent triggers npm run test:coverage and enforces the repository's 80%+ coverage policy, ensuring quality gates are met before the iteration completes.

Command Structure and Integration

The TDD workflow is exposed through the /tdd slash command, defined in commands/tdd.md. This command serves as the entry point that activates the agent and coordinates with the broader workflow system.

User: /tdd I need a function to calculate market liquidity score

When invoked, the agent follows the complete workflow documented in agents/tdd-guide.md. The command integrates with:

• /plan — for task breakdown before TDD begins
• /code-review — for post-implementation validation
• /test-coverage — for quality gate enforcement

Files Powering the TDD Guide Agent

File	Purpose
agents/tdd-guide.md	Defines the agent's role, available tools, and the full TDD workflow specification
commands/tdd.md	Implements the /tdd slash command and orchestration logic
skills/tdd-workflow/	Contains skill assets for generating scaffolds, tests, and refactoring suggestions
scripts/lib/package-manager.js	Supports dependency installation for test execution

Practical Example: Liquidity Score Calculator

The following example from the repository demonstrates a complete iteration through the TDD guide agent's workflow.

RED Phase: Failing Test

// lib/liquidity.test.ts
import { calculateLiquidityScore } from './liquidity'

describe('calculateLiquidityScore', () => {
  it('should return high score for liquid market', () => {
    const market = {
      totalVolume: 100000,
      bidAskSpread: 0.01,
      activeTraders: 500,
      lastTradeTime: new Date()
    }
    const score = calculateLiquidityScore(market)
    expect(score).toBeGreaterThan(80)
  })
})

Running npm test lib/liquidity.test.ts produces a failure—the function throws "Not implemented", confirming the RED state.

GREEN Phase: Minimal Implementation

// lib/liquidity.ts
export function calculateLiquidityScore(market: MarketData): number {
  if (market.totalVolume === 0) return 0
  const volumeScore = Math.min(market.totalVolume / 1000, 100)
  const spreadScore = Math.max(100 - (market.bidAskSpread * 1000), 0)
  const traderScore = Math.min(market.activeTraders / 10, 100)
  const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) /
    (1000 * 60 * 60)
  const recencyScore = Math.max(100 - (hoursSinceLastTrade * 10), 0)

  return Math.min(
    volumeScore * 0.4 +
    spreadScore * 0.3 +
    traderScore * 0.2 +
    recencyScore * 0.1,
    100
  )
}

Re-running the test suite now passes, achieving GREEN.

REFACTOR Phase: Clean Implementation

// lib/liquidity.ts (refactored)
const WEIGHTS = { VOLUME: 0.4, SPREAD: 0.3, TRADERS: 0.2, RECENCY: 0.1 }
const SCALE = { VOLUME: 1000, SPREAD: 1000, TRADERS: 10, RECENCY_PENALTY: 10 }

function clamp(v: number, min: number, max: number) {
  return Math.min(Math.max(v, min), max)
}

export function calculateLiquidityScore(market: MarketData): number {
  if (market.totalVolume === 0) return 0

  const volumeScore = Math.min(market.totalVolume / SCALE.VOLUME, 100)
  const spreadScore = clamp(100 - market.bidAskSpread * SCALE.SPREAD, 0, 100)
  const traderScore = Math.min(market.activeTraders / SCALE.TRADERS, 100)

  const hoursSinceLastTrade = (Date.now() - market.lastTradeTime.getTime()) /
    (1000 * 60 * 60)
  const recencyScore = clamp(
    100 - hoursSinceLastTrade * SCALE.RECENCY_PENALTY,
    0,
    100
  )

  const weightedScore =
    volumeScore * WEIGHTS.VOLUME +
    spreadScore * WEIGHTS.SPREAD +
    traderScore * WEIGHTS.TRADERS +
    recencyScore * WEIGHTS.RECENCY

  return clamp(weightedScore, 0, 100)
}

Tests remain green after refactoring, confirming behavior preservation.

Coverage Verification

npm run test:coverage

# ➜ coverage report shows >100% for liquidity.ts (target ≥80%)

Benefits of Agent-Driven Iterative Workflows

• Regression prevention — Every change is validated by the same test suite that defined it
• Minimal implementation — Scope is constrained to actual requirements, reducing over-engineering
• Safe refactoring — Structural improvements are made with continuous verification
• Enforced quality gates — Coverage thresholds block incomplete work
• Incremental development — Large features decompose into small, verifiable steps

Summary

• The TDD guide agent enforces a strict RED → GREEN → REFACTOR cycle for every code change
• Workflow entry is through /tdd command (commands/tdd.md) with logic defined in agents/tdd-guide.md
• Each iteration includes interface scaffolding, failing test generation, minimal implementation, and coverage verification
• The agent maintains test suite integrity throughout refactoring phases
• Integration with /plan, /code-review, and /test-coverage commands creates a cohesive development environment

Frequently Asked Questions

How do I invoke the TDD guide agent?

Use the /tdd slash command followed by your feature description. The command parses your request and activates the agent, which then guides you through the complete workflow defined in agents/tdd-guide.md.

What happens if my tests don't fail during the RED phase?

The TDD guide agent treats this as an error condition. A test that passes before implementation exists indicates a defective test—it cannot distinguish correct from incorrect behavior. The agent will flag this and require test revision.

Can I skip the refactoring phase?

While technically possible, the agent strongly discourages this. The REFACTOR phase is where code quality improves without behavior change. Skipping it accumulates technical debt that future iterations must address at higher cost.

How does the agent enforce the 80% coverage threshold?

After achieving green tests, the agent automatically executes npm run test:coverage. If coverage falls below the threshold defined in repository policy, the iteration cannot be considered complete. The agent will suggest additional test cases or implementation adjustments to meet the requirement.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}