markitect-main/docs/manuals/tddai.1.md

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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.