tdd-specflow

TDD SpecFlow - Claude Code Plugin & Marketplace

A comprehensive Test-Driven Development workflow plugin for Claude Code that combines TDD with Specification by Example (BDD). Streamline your development process with intelligent agents that guide you through requirements analysis, technical design, and the complete RED-GREEN-REFACTOR cycle.

Note: This repository also serves as a plugin marketplace infrastructure, currently hosting the tdd-specflow plugin with support for adding more plugins in the future. See MARKETPLACE.md for details on the marketplace structure.

Overview

TDD SpecFlow provides a complete, automated workflow for building features using Test-Driven Development and Behavior-Driven Development principles. The plugin includes specialized agents for each phase of development and slash commands that orchestrate the entire process.

Key Features

• Complete TDD Workflow: Automated RED-GREEN-REFACTOR cycle with progress tracking
• Specification by Example: Transform acceptance criteria into concrete test scenarios with Given-When-Then format
• Requirements Analysis: Structured specification generation from JIRA tickets or user stories
• Technical Design: Automated technical design documents following architectural patterns
• 9 Specialized Agents: Each agent is an expert in their specific domain
• 5 Slash Commands: Orchestrate the entire development workflow
• Progress Tracking: Visual checkboxes track progress through each TDD phase

Installation

Install the plugin using Claude Code's plugin command:

/plugin install https://github.com/dgomezs/claude-code

Or if using a local clone:

/plugin install /path/to/claude-code

Quick Start

1. Create Requirements Specification

Start with a JIRA ticket, user story, or direct prompt:

/create-spec ticket.md

or with a direct prompt:

/create-spec "Add user authentication with JWT tokens"

This creates requirements.md with testable acceptance criteria in Given-When-Then format.

2. Generate Test Scenarios

Transform acceptance criteria into detailed test scenarios:

/test-scenarios <task-directory>

This creates:

• scenarios.md - High-level scenario overview with TDD tracking checkboxes
• test-scenarios/happy-path.md - Successful flow scenarios
• test-scenarios/error-cases.md - Error handling scenarios
• test-scenarios/edge-cases.md - Boundary and edge cases

3. Create Technical Design

Generate an implementation plan following your project's architecture:

/create-tech-design <task-directory>

This creates tech-design.md with:

• Component architecture
• Implementation strategy
• Testing guidelines
• Integration points

4. Run TDD Implementation

Execute the complete RED-GREEN-REFACTOR cycle:

/start-tdd <task-directory>

The orchestrator will:

1. Detect which phase you're in (RED, GREEN, or REFACTOR)
2. Launch the appropriate specialized agent
3. Track progress with checkboxes in scenarios.md
4. Suggest commits after each phase
5. Continue until all scenarios are complete

Workflow Overview

┌─────────────────────────────────────────────────────────────┐
│                    TDD SpecFlow Workflow                    │
└─────────────────────────────────────────────────────────────┘

1. Requirements Analysis
   ↓
   /create-spec → requirements.md

2. Test Scenarios
   ↓
   /test-scenarios → scenarios.md + test-scenarios/

3. Technical Design
   ↓
   /create-tech-design → tech-design.md

4. TDD Implementation Loop
   ↓
   /start-tdd → RED-GREEN-REFACTOR cycle

   For each scenario:
   ┌─────────────────────────────────────┐
   │  RED: Write failing test            │
   │    ↓                                │
   │  GREEN: Make it pass (minimal code) │
   │    ↓                                │
   │  REFACTOR: Improve quality          │
   └─────────────────────────────────────┘

Slash Commands

/create-spec

Purpose: Analyze requirements and create structured specification

Usage:

/create-spec <ticket-path | prompt> [research.md]

Examples:

/create-spec docs/tickets/AUTH-123.md
/create-spec "Add password reset functionality" research.md
/create-spec "Implement user profile editing"

Output: requirements.md with testable acceptance criteria

---

/test-scenarios

Purpose: Generate detailed test scenarios from requirements

Usage:

/test-scenarios <task-directory> [operation-prompt]

Examples:

/test-scenarios docs/tasks/task-001/
/test-scenarios docs/tasks/task-001/ "Add scenario for concurrent access"

Output:

• scenarios.md - Overview with TDD tracking
• test-scenarios/happy-path.md
• test-scenarios/error-cases.md
• test-scenarios/edge-cases.md

---

/create-tech-design

Purpose: Create technical design from requirements