# tddai(1) - Test-Driven Development AI Assistant

## SYNOPSIS

**tddai** [*OPTIONS*] *COMMAND* [*ARGS*...]

## DESCRIPTION

TDDAI (Test-Driven Development AI) is a comprehensive CLI tool for managing TDD workflows, issue tracking, and development project organization. It provides intelligent automation for the complete development lifecycle with focus on test-driven development practices.

TDDAI integrates issue management, workspace organization, test coverage analysis, and project management into a unified workflow that supports the TDD8 methodology (Issue-Test-Red-Green-Refactor-Document-Refine-Publish).

## COMMANDS

### Workspace Management

**workspace-status**
: Show current workspace status
: Displays active issues, workspace state, and pending tasks

**start-issue** *ISSUE_NUMBER*
: Start working on an issue
: Initializes workspace, sets up test environment, creates issue context

**finish-issue**
: Finish current issue workspace
: Completes TDD cycle, updates issue status, cleans up workspace

**add-test**
: Show guidance for adding tests
: Provides TDD-specific guidance and test templates

### Issue Management

**list-issues**
: List all issues with status and priority
: Shows comprehensive issue overview with filtering options

**list-open-issues**
: List only open issues (active backlog)
: Focuses on actionable items in current sprint

**show-issue** *ISSUE_NUMBER*
: Show detailed issue information
: Displays description, comments, status, and related context

**close-issue** *ISSUE_NUMBER* [*COMMENT*]
: Close an issue with optional comment
: Marks issue complete and records completion context

**analyze-coverage** *ISSUE_NUMBER*
: Analyze test coverage for specific issue
: Shows coverage metrics and testing completeness

### Issue Creation

**create-issue** *TITLE* *BODY* [*OPTIONS*]
: Create a new issue
: Basic issue creation with title and description

**create-enhancement** *TITLE* *USE_CASE* [*OPTIONS*]
: Create a structured enhancement issue
: Uses enhancement template with use cases and acceptance criteria

**create-from-template** *TEMPLATE_FILE* [*VARIABLES*]
: Create issue from template file
: Template-based issue creation with variable substitution

### Project Management

**setup-project-mgmt**
: Setup project management labels and milestones
: Initializes project structure and management framework

**project-overview**
: Show project management overview
: Dashboard view of project status, milestones, and progress

**set-issue-state** *ISSUE_NUMBER* *STATE*
: Set issue project state
: Workflow state management (Todo, In Progress, Done, etc.)

**set-issue-priority** *ISSUE_NUMBER* *PRIORITY*
: Set issue priority level
: Priority management (low, medium, high, critical)

**create-milestone** *TITLE* [*DESCRIPTION*]
: Create a new milestone for project organization
: Milestone-based project planning and tracking

**list-milestones**
: List all project milestones
: Shows milestone progress and associated issues

**assign-to-milestone** *ISSUE_NUMBER* *MILESTONE_ID*
: Assign issue to milestone
: Links issues to project milestones for planning

### Data Export and Integration

**issue-index** [*OPTIONS*]
: Output compact issue index for Unix processing
: Machine-readable issue data for scripts and automation

### Configuration Management

**config-show**
: Display current configuration values
: Shows effective configuration from all sources

**config-validate**
: Validate current configuration
: Checks configuration consistency and completeness

**config-troubleshoot**
: Run comprehensive configuration troubleshooting
: Diagnoses configuration issues and provides solutions

**config-files**
: Check configuration files status
: Shows configuration file locations and validation

## OPTIONS

**-h, --help**
: Show help message and exit

**--verbose**
: Enable verbose output for debugging

**--config** *PATH*
: Specify custom configuration file path

## TDD8 METHODOLOGY

TDDAI implements the TDD8 workflow methodology:

1. **ISSUE** - Define problem and requirements
2. **TEST** - Write tests before implementation
3. **RED** - Ensure tests fail initially
4. **GREEN** - Implement minimum viable solution
5. **REFACTOR** - Improve code quality and design
6. **DOCUMENT** - Update documentation and examples
7. **REFINE** - Performance optimization and polish
8. **PUBLISH** - Release and communicate changes

### TDD8 Workflow Commands

```bash
# Start TDD cycle
tddai start-issue 42

# Check workspace status
tddai workspace-status

# Add test guidance
tddai add-test

# Analyze test coverage
tddai analyze-coverage 42

# Complete TDD cycle
tddai finish-issue

# Close issue with completion
tddai close-issue 42 "Implemented with full test coverage"
```

## EXAMPLES

### Basic Workflow

```bash
# Show workspace status
tddai workspace-status

# Start working on an issue
tddai start-issue 123

# Get test guidance
tddai add-test

# Check coverage for current issue
tddai analyze-coverage 123

# Complete the issue
tddai finish-issue
```

### Issue Management

```bash
# List all open issues
tddai list-open-issues

# Show specific issue details
tddai show-issue 42

# Create new enhancement
tddai create-enhancement "Add caching" "Improve performance by caching frequent queries"

# Set issue priority
tddai set-issue-priority 42 high

# Close completed issue
tddai close-issue 42 "Feature implemented and tested"
```

### Project Management

```bash
# Setup project management structure
tddai setup-project-mgmt

# View project overview
tddai project-overview

# Create milestone
tddai create-milestone "Version 1.0" "Initial release milestone"

# Assign issue to milestone
tddai assign-to-milestone 42 1

# Set issue state
tddai set-issue-state 42 "In Progress"
```

### Data Export and Automation

```bash
# Export issue index for processing
tddai issue-index --format json > issues.json

# Export specific format
tddai issue-index --format csv --filter-state open

# Unix pipeline processing
tddai issue-index --format tsv | cut -f1,3 | sort
```

### Configuration Management

```bash
# Show current configuration
tddai config-show

# Validate configuration
tddai config-validate

# Troubleshoot config issues
tddai config-troubleshoot

# Check config file status
tddai config-files
```

## CONFIGURATION

TDDAI uses a hierarchical configuration system:

### Configuration Sources (priority order)
1. **Command-line options** (highest)
2. **Environment variables** (`TDDAI_*`)
3. **`.env.tddai` file** (project-specific)
4. **Default values** (lowest)

### Configuration Files

**`.env.tddai`**
: Project-specific configuration file
: Key-value pairs for project settings

**`~/.tddai/config.yml`**
: User-level configuration
: Personal defaults and preferences

### Common Configuration Variables

**TDDAI_GITEA_URL**
: Gitea server URL for issue tracking

**TDDAI_GITEA_TOKEN**
: API token for Gitea authentication

**TDDAI_PROJECT_ROOT**
: Project root directory path

**TDDAI_WORKSPACE_DIR**
: Workspace directory for issue work

**TDDAI_DEFAULT_MILESTONE**
: Default milestone for new issues

**TDDAI_COVERAGE_THRESHOLD**
: Minimum test coverage percentage

## INTEGRATION

### Issue Tracking Systems

TDDAI integrates with various issue tracking systems:

- **Gitea** - Primary integration with API support
- **GitHub** - Via API (configuration required)
- **Local files** - File-based issue tracking

### CI/CD Integration

```bash
# In CI/CD pipelines
tddai config-validate || exit 1
tddai analyze-coverage $ISSUE_NUMBER
tddai issue-index --format json > artifacts/issues.json
```

### Development Workflow Integration

```bash
# Git hooks integration
echo "tddai workspace-status" > .git/hooks/pre-commit

# Makefile integration
test-coverage:
	tddai analyze-coverage $(ISSUE)

issue-status:
	tddai project-overview
```

## FILES

**`.env.tddai`**
: Project configuration file

**`.tddai/workspace/`**
: Issue workspace directory

**`~/.tddai/`**
: User configuration directory

**`tddai.log`**
: Activity log file (when logging enabled)

## EXIT STATUS

**0**
: Success

**1**
: General error (command failed, invalid arguments)

**2**
: Configuration error (missing config, invalid values)

**3**
: Issue tracking error (API failure, network issues)

**4**
: Workspace error (workspace conflicts, file issues)

## ENVIRONMENT

**TDDAI_GITEA_URL**
: Gitea server URL

**TDDAI_GITEA_TOKEN**
: Gitea API authentication token

**TDDAI_PROJECT_ROOT**
: Project root directory

**TDDAI_WORKSPACE_DIR**
: Issue workspace directory

**TDDAI_VERBOSE**
: Enable verbose logging (any non-empty value)

**TDDAI_CONFIG**
: Custom configuration file path

## WORKFLOW INTEGRATION

### With MarkiTect

```bash
# Document-driven development
markitect schema-generate requirements.md
tddai create-issue "Implement feature" "$(markitect content-get requirements.md)"
tddai start-issue 42
```

### With Issue CLI

```bash
# Pure issue management with TDDAI workflow
issue create "Bug fix" "Description"
tddai start-issue 42  # Start TDD workflow
issue assign 42 milestone-1  # Project management
```

## SEE ALSO

**markitect**(1), **issue**(1)

TDD8 Methodology Documentation
Project Management Integration Guide
Configuration Reference Manual

## BUGS

Report bugs at project issue tracker

## AUTHORS

TDDAI development team

## COPYRIGHT

Copyright (c) 2025 MarkiTect Project. Licensed under MIT License.