Aditi Pre-Implementation Todo List

This document outlines all tasks and prerequisites that must be completed before beginning the implementation of Aditi based on the Claude Code implementation plan.

🎉 Phase 0 Status: COMPLETE!

Key Achievements:

• ✅ Vale container integration fully implemented
• ✅ Podman/Docker runtime detection and management
• ✅ AsciiDocDITA styles automatic downloading
• ✅ Init command with Rich progress indicators
• ✅ Comprehensive test scripts validating the solution
• ✅ Documentation and implementation guides created

🚀 Phase 1 Status: COMPLETE!

Key Achievements:

• ✅ Modern Python packaging with pyproject.toml
• ✅ Complete CLI framework with Typer and Rich
• ✅ Configuration management with Pydantic models
• ✅ Git guidance module for workflow assistance
• ✅ Comprehensive test suite (94% test success rate)
• ✅ Package structure with proper exports
• ✅ Working CLI: pip install -e . and aditi --help functional

Ready for Phase 2: Rule Engine Implementation

Environment Setup Prerequisites

1. Development Tools Installation

• Install Python 3.11 or later
• Install Podman (rootless container runtime)
• Install Git
• Install Ruby 3.1+ and Bundler (for Jekyll docs)
• Install GitLab CLI (glab) for GitLab integration
• Install GitHub CLI (gh) for GitHub integration
• Verify VS Code with Claude Code extension is set up

2. Container Setup

• Pull the Vale linter container: podman pull ghcr.io/rolfedh/asciidoc-dita-toolkit-prod Using docker.io/jdkato/vale:latest
• Test Podman can run the Vale container
• Verify container has access to local file system
• Test Vale with sample AsciiDoc files

Note: Implementation uses the official Vale Docker image (docker.io/jdkato/vale:latest) instead of the custom image. The AsciiDocDITA styles are downloaded automatically via Vale’s package system.

3. Python Development Environment

• Set up virtual environment for Python development
• Install development tools: pytest, mypy, ruff, black
• Install Click or Typer for CLI framework
• Install Rich for enhanced CLI output
• Configure IDE for Python development

Project Foundation Tasks

4. Repository Setup

• Create new Git repository for Aditi
• Set up proper .gitignore for Python projects
• Configure branch protection rules
• Set up commit signing (if required)

5. Documentation Review

• Review and understand AsciiDocDITA ruleset
• Document all Vale rules that need implementation
• Categorize rules by fix type (fully/partially/non-deterministic)
• Create sample AsciiDoc files for testing each rule

6. Test Data Preparation

• Create test AsciiDoc files with various violations
• Prepare valid AsciiDoc files for regression testing
• Document expected outcomes for each test file
• Create edge case examples

Design Decisions

7. Architecture Finalization

• Confirm CLI framework choice: Typer (Click vs Typer)
• Define exact JSON schema for configuration
• Document git workflow for users
• Define PR template format
• Specify report output format

8. Rule Processing Strategy

• Define rule execution order and dependencies
• Document violation data structure
• Design fix application algorithm
• Plan rollback mechanism

9. User Experience Design

• Design interactive prompts for journey command
• Create error message templates
• Define progress indicator styles
• Plan confirmation prompt flows

Integration Planning

10. Vale Integration

• Document Vale output format (JSON output implemented)
• Create Vale output parser design (JSON parsing in ValeContainer)
• Plan streaming output handling (subprocess with capture_output)
• Design error recovery for container failures (comprehensive error handling)

11. Git Integration

• Document required git operations
• Create git command templates for users
• Plan conflict resolution guidance
• Design branch naming conventions

12. CI/CD Setup

• Create GitHub Actions workflow template
• Set up PyPI account for distribution
• Configure TestPyPI for testing
• Plan versioning strategy

Pre-Implementation Research

13. Technical Spikes

• Test Podman Python bindings (using subprocess instead)
• Verify Vale container networking requirements (no networking needed)
• Test GitLab/GitHub CLI automation capabilities
• Validate Rich library features for CLI (progress bars working)

14. Performance Benchmarks

• Measure Vale processing time for large files
• Test container startup/shutdown overhead
• Benchmark file I/O operations
• Plan optimization strategies

Documentation Preparation

15. User Documentation Templates

• Create README template
• Design user guide structure
• Plan API documentation format
• Create troubleshooting guide outline

16. Developer Documentation

• Document coding standards
• Create contribution guidelines
• Design architecture diagrams
• Plan code review checklist

Risk Mitigation

17. Dependency Management

• Lock down all dependency versions
• Create fallback plans for external services
• Document minimum system requirements
• Plan for backwards compatibility

18. Security Review

• Review Podman security best practices
• Plan secrets management approach
• Document file system permission requirements
• Create security testing checklist

Implementation Readiness

19. Development Workflow

• Set up development branch strategy
• Create PR template
• Configure code formatting tools
• Set up pre-commit hooks

20. Testing Framework

• Set up pytest configuration
• Create test fixture directory structure
• Design mock objects for external dependencies
• Plan integration test scenarios

Final Checklist Before Implementation

21. Team Alignment

• Review implementation plan with stakeholders
• Confirm timeline and milestones
• Assign responsibilities (if team project)
• Schedule regular check-ins

22. Success Metrics

• Define performance benchmarks
• Set code coverage targets
• Establish user acceptance criteria
• Plan feedback collection method

Notes

• Complete items in order as some tasks depend on others
• Document any decisions or changes to the plan
• Keep this list updated as new requirements emerge
• Each completed task should be tested before marking done

Estimated Time Investment

• Environment Setup: 2-3 hours
• Project Foundation: 3-4 hours
• Design Decisions: 2-3 hours
• Integration Planning: 2-3 hours
• Pre-Implementation Research: 3-4 hours
• Documentation Preparation: 2-3 hours
• Risk Mitigation: 1-2 hours
• Implementation Readiness: 2-3 hours

Total Pre-Implementation Time: 17-25 hours

This investment ensures a smooth implementation phase and reduces technical debt.