feat: Complete test-fixing agent implementation and CLI consolidation
- 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>
This commit is contained in:
419
docs/manuals/tddai.1.md
Normal file
419
docs/manuals/tddai.1.md
Normal file
@@ -0,0 +1,419 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user