tdd-kata

TDD Kata Claude Plugin

A Claude Code plugin for practicing Test-Driven Development through code katas with strict Red-Green-Refactor cycle enforcement.

Overview

This plugin helps you practice TDD by guiding you through kata exercises with three specialized agents that enforce proper TDD discipline:

• 🔴 Tester Agent (RED) - Writes failing tests for the next behavior
• 🟢 Implementer Agent (GREEN) - Writes minimal code to pass the test
• 🔵 Refactorer Agent (REFACTOR) - Improves code structure while keeping tests green

Features

• ✅ Automatic handoff between TDD cycle phases
• ✅ Strict enforcement: tests must fail before implementation, pass before refactoring
• ✅ Shared TODO list with lessons learned across all agents
• ✅ Language-agnostic support with automated toolchain setup
• ✅ Kata constraint support (object calisthenics patterns)
• ✅ Session persistence for resuming kata practice
• ✅ Conventional commit messages for each phase

Prerequisites

• Claude Code CLI (claude) installed and configured
• Git for version control (automatically initialized by the plugin)
• Language toolchain for your chosen language, for example:
  • Rust: cargo (install from rustup.rs)
  • TypeScript/JavaScript: node and npm
  • Python: python3 and pip
  • Java: java and gradle or maven
  • Go: go toolchain

The plugin will detect existing toolchains and guide you through installation if needed.

⚡ Quick Install

Option 1: Local Usage (Temporary)

Use the plugin for a specific session without installing it globally:

# Clone the repository
git clone https://github.com/xpepper/tdd-kata-claude-plugin.git

# Run Claude Code with the plugin
claude --plugin-dir ./tdd-kata-claude-plugin

This works from any directory by pointing to the plugin location:

claude --plugin-dir /path/to/tdd-kata-claude-plugin

Option 2: Global Installation (Persistent)

Install the plugin globally so it's automatically available in all sessions:

# Clone and copy to Claude plugins directory
git clone https://github.com/xpepper/tdd-kata-claude-plugin.git
mkdir -p ~/.claude/plugins
cp -r tdd-kata-claude-plugin ~/.claude/plugins/tdd-kata

# Now just run Claude normally - the plugin auto-loads
claude

Verify Installation

Check that the plugin loaded successfully:

# Start Claude Code
claude

# Check available commands (should see start-kata, kata-status, etc.)
/help

🚀 Quick Start

Try the plugin with the classic FizzBuzz kata:

# 1. Create a practice directory
mkdir -p ~/katas/fizzbuzz
cd ~/katas/fizzbuzz

# 2. Create a kata description file
cat > kata.md <<'EOF'
# FizzBuzz Kata

## Description
Write a program that returns:
- "Fizz" for multiples of 3
- "Buzz" for multiples of 5
- "FizzBuzz" for multiples of both
- The number as a string otherwise

## Examples
- Input: 1 → Output: "1"
- Input: 3 → Output: "Fizz"
- Input: 5 → Output: "Buzz"
- Input: 15 → Output: "FizzBuzz"

## Constraints
- One level of indentation per method
- Don't use the ELSE keyword
EOF

# 3. Start Claude Code with the plugin
# Local usage (Option 1):
claude --plugin-dir /path/to/tdd-kata-claude-plugin

# Global installation (Option 2):
claude

# 4. In Claude Code, run:
/start-kata kata.md

# 5. Follow the agent guidance through RED-GREEN-REFACTOR cycles!

Usage

Starting a Kata

Start a new kata session with a description file:

/start-kata path/to/kata-description.md

Or provide the description interactively:

/start-kata

The plugin will:

1. Parse kata description and constraints
2. Ask clarifying questions
3. Detect or ask for programming language
4. Set up toolchain and test framework
5. Initialize git repository
6. Automatically launch the Tester agent to begin RED phase

Kata Description Format

Create a markdown file describing your kata:

# Kata Name

## Description
[What the program should do]

## Constraints (optional)
- One level of indentation per method
- Don't use the ELSE keyword
- Wrap all primitives and Strings
- First class collections

## Examples
[Input/output examples]

Workflow

Once started, the plugin automatically cycles through TDD phases:

1. RED Phase (Tester Agent):

   • Writes next failing test
   • Verifies test fails
   • Updates TODO list and lessons learned
   • Commits with test: ...
   • Launches Implementer Agent

2. GREEN Phase (Implementer Agent):

   • Writes minimal code to pass test
   • Verifies test passes
   • Updates TODO list and lessons learned
   • Commits with feat: ...
   • Launches Refactorer Agent

3. REFACTOR Phase (Refactorer Agent):

   • Analyzes code for improvements
   • Refactors while keeping tests green
   • Updates TODO list and lessons learned
   • Commits with refactor: ... (if changes made)
   • Asks: Continue or complete kata?

Additional Commands

Check current kata status: