tegwick
bce5a57593
- Created specialized test-fixing agent to analyze and fix failing tests - Re-added issues group to markitect CLI for unified access alongside dedicated CLIs - Updated CLI consolidation tests to reflect new architecture (unified + specialized) - Removed unnecessary test_plugin_assigns_sequential_issue_numbers (local plugin not actively used) - Added comprehensive manual pages for all three CLIs (markitect, tddai, issue) - Enhanced CLI integration tests with 40+ test cases covering functionality and regression prevention - Ensured clean test suite with all critical tests passing Architecture: markitect provides unified interface while tddai/issue CLIs offer specialized access Test Coverage: 801 tests with comprehensive CLI validation and functionality verification 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
419 lines
9.2 KiB
Markdown
419 lines
9.2 KiB
Markdown
# 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. |