Kiro TDD Workflow

🎯 A complete Test-Driven Development (TDD) workflow tool that supports multiple modern frontend frameworks.

Key Features

• 📝 Four-Stage TDD Process - Design → Test → Implement → Verify
• 🎨 Complete Design Templates - Standardized feature design documentation
• 🧪 Test-Driven Development - Ensures code quality and functionality
• ⚙️ Development Guidelines Integration - DRY, KISS principles, TypeScript strict mode
• 🌍 Internationalization Support - Complete i18n planning and implementation
• 🎭 Theme System - CSS variables system with dark/light theme support
• 📱 Responsive Design - Mobile-first design principles

Quick Start

Installation

# Initialize TDD workflow in your project
npx kiro-tdd-workflow init

# Configure framework type and development guidelines
npx kiro-tdd-workflow setup

# Or use interactive installation
npx kiro-tdd-workflow

AI Assistant Integration

After initialization, use .kiro/dev/ai-initialization-guide.md to confirm setup with your AI assistant:

1. Copy the content of ai-initialization-guide.md
2. Share it with your AI assistant (Claude, ChatGPT, Kiro, etc.)
3. AI will help check for missing files and configurations
4. Complete remaining setup based on suggestions
5. Start using the TDD workflow

Basic Usage

# 1. Initialize workflow
npx kiro-tdd-workflow init

# 2. Configure framework type (optional)
npx kiro-tdd-workflow setup
# Choose default templates or skip to create blank files

# 3. Confirm setup with AI
# Copy .kiro/dev/ai-initialization-guide.md content to AI assistant

# 4. Start developing new features
# Use in your AI assistant:
"Design useNotification composable"

# 5. Follow the four-stage development process
"Write tests"        # Stage 1
"Implement feature"  # Stage 2  
"Run tests"         # Stage 3

Four-Stage TDD Process

Stage 0: Design Planning 📝

• Requirements analysis and solution discussion
• Generate complete feature design documentation
• Follow all development guidelines and best practices

Stage 1: Write Tests 🧪

• Write unit tests based on design documentation
• Tests should fail (Red)
• Use Vitest testing framework

Stage 2: Implement Feature ⚙️

• Implement feature based on design documentation
• Make tests pass (Green)
• Follow DRY, KISS principles

Stage 3: Run Tests & Refactor ✅

• Run tests to confirm they pass
• Refactor and optimize code (Refactor)
• Feature development complete

Directory Structure

After initialization, the following structure will be created in your project:

.kiro/
├── dev/
│   ├── README.md                    # Workflow documentation
│   ├── tdd-workflow.md              # Complete process documentation
│   ├── design-template.md           # Design document template
│   ├── ai-initialization-guide.md   # AI initialization guide
│   └── designs/                     # Feature design documents directory
│       └── README.md
└── steering/
    └── development.md               # Development guidelines & best practices

Core Principles

DRY Principle (Don't Repeat Yourself)

• Extract shared logic into composables
• Create reusable UI components
• Unified API calling approach
• Avoid duplicate style definitions

KISS Principle (Keep It Simple, Stupid)

• Prioritize simple and direct solutions
• Avoid over-abstraction and complex design
• Single responsibility components, easy to understand
• Function length < 50 lines, nesting < 3 levels

TypeScript Strict Mode

• Avoid using any type
• Complete Props and API interface definitions
• Explicit function return types
• Appropriate type organization strategy

Supported Tech Stack

Frontend Frameworks

• ✅ React + Next.js - App Router, Shadcn/ui components
• ✅ Vue 3 + Nuxt 3 - Composition API, SSR support
• ✅ Vue 3 + Vite - Lightweight development environment
• ✅ TypeScript - Strict type checking, universal project support

UI Component Libraries

• ✅ Shadcn/ui - React ecosystem
• ✅ Shadcn Vue - Vue ecosystem
• ✅ CSS Variables System - Theming design
• ✅ Responsive Design - Mobile-first approach

Testing Frameworks

• ✅ Vitest - Fast testing for Vue projects
• ✅ Jest + Testing Library - React project testing
• ✅ @vue/test-utils - Vue component testing
• ✅ Test-Driven Development - Complete TDD process

State Management

• ✅ Pinia - Vue 3 official state management
• ✅ Zustand/Redux - React state management
• ✅ Composition API - Modern state management

Internationalization

• ✅ Vue i18n - Vue multilingual support
• ✅ Next.js i18n - React internationalization
• ✅ Complete Translation Planning - English/Chinese support

Usage Examples

Vue Project - Developing Composable

# Stage 0: Design
"Design a useNotification composable"
# → Create .kiro/dev/designs/use-notification-composable.md

# Stage 1: Test
"Write tests"
# → Create composables/__tests__/useNotification.test.ts

# Stage 2: Implementation
"Implement feature"
# → Create composables/useNotification.ts

# Stage 3: Verification
"Run tests"
# → Execute tests and confirm they pass

React Project - Developing Custom Hook

# Stage 0: Design
"Design a useNotification hook"
# → Create .kiro/dev/designs/use-notification-hook.md

# Stage 1: Test
"Write tests"
# → Create hooks/__tests__/useNotification.test.ts

# Stage 2: Implementation
"Implement feature"
# → Create hooks/useNotification.ts

# Stage 3: Verification
"Run tests"
# → Execute tests and confirm they pass

Developing UI Components

# Stage 0: Design
"Design a StatusBadge component"
# → Create .kiro/dev/designs/status-badge-component.md

# Stage 1: Test
"Write tests"
# → React: components/__tests__/StatusBadge.test.tsx
# → Vue: components/UI/__tests__/StatusBadge.test.ts

# Stage 2: Implementation
"Implement feature"
# → React: npx shadcn-ui@latest add badge
# → Vue: npx shadcn-vue@latest add badge
# → Create corresponding component files

# Stage 3: Verification
"Run tests"
# → Execute tests and confirm they pass

Command Reference

CLI Commands

# Initialize project
npx kiro-tdd-workflow init

# Interactive setup
npx kiro-tdd-workflow setup

# Show usage guide
npx kiro-tdd-workflow help-guide

# Interactive menu
npx kiro-tdd-workflow

AI Assistant Commands

# Complete TDD process
"Design [feature name]"     # Stage 0: Design planning
"Write tests"              # Stage 1: Write tests
"Implement feature"        # Stage 2: Implement feature
"Run tests"               # Stage 3: Run tests

# Simplified process (for simple fixes)
"Fix bug: [issue description]"
"Adjust UI: [adjustment content]"
"Add feature: [brief description]"

# Other commands
"Adjust design"
"Refactor code"
"View design document"

Development Checklist

New Feature Development

• Follow DRY principle (avoid duplicate code)
• Follow KISS principle (keep simple and intuitive)
• Use CSS variables (no hardcoded colors)
• All text uses i18n (t() function)
• Complete TypeScript type definitions
• Components use Composition API
• Responsive design (Media Queries)
• Single responsibility functions, length < 50 lines
• Avoid deep nesting (< 3 levels)

UI Component Development

• Check Shadcn Vue components first
• Check existing project components
• Use CSS variables for theme consistency
• Support dark/light theme switching
• Component props < 10
• Accessibility (a11y) considerations

Contributing

Issues and Pull Requests are welcome!

Local Development

# Install dependencies
npm install

# Development mode
npm run dev

# Build
npm run build

# Test
npm test

License

MIT License - See LICENSE file for details.

Related Links

• GitHub Repository
• Issues
• Changelog
• Publishing Guide

Support

For questions or suggestions:

1. Check .kiro/dev/tdd-workflow.md for complete process documentation
2. Refer to .kiro/dev/design-template.md design template
3. Read .kiro/steering/development.md development guidelines
4. Submit a GitHub Issue

---

Make TDD your development habit and improve code quality and development efficiency! 🚀