markitect-main/DIRECTORY_STRUCTURE_OPTIMIZATION_GAMEPLAN.md

# Directory Structure Optimization Gameplan

**Status**: Draft
**Created**: 2025-09-27
**Priority**: Medium
**Complexity**: High
**Estimated Duration**: 18-25 hours over 3-5 days

## Executive Summary

This gameplan outlines a systematic restructuring of the MarkiTect repository to adopt modern Python packaging standards, eliminate code duplication, and improve maintainability. The migration follows a 9-phase approach designed to minimize risk and ensure continuous functionality.

### Key Benefits
- **Standards Compliance**: Modern Python `src/` layout
- **Reduced Complexity**: Eliminates 3 overlapping CLI implementations
- **Better Organization**: Clear separation of domain, application, and infrastructure concerns
- **Improved Maintainability**: Consolidated documentation and logical code organization
- **Enhanced Developer Experience**: Cleaner structure for easier navigation and onboarding

### Critical Success Factors
- All tests must pass before migration begins (current: 305 passed, 2 skipped)
- Phased approach with validation after each step
- Comprehensive backup and rollback strategy
- Automated import path updates

### Go/No-Go Criteria
- ✅ Test suite is green
- ✅ Clean git state with no uncommitted changes
- ✅ Development environment is stable
- ✅ Team alignment on migration approach

## Overview
This gameplan outlines the systematic restructuring of the MarkiTect repository to follow modern Python packaging standards and improve maintainability. The migration will be done in phases to minimize disruption and ensure everything continues working.

## Current Structure Analysis

### Identified Issues
1. **Multiple overlapping CLI implementations** (`markitect/cli.py`, `cli/`, `tddai_cli.py`)
2. **Scattered application logic** across `markitect/`, `services/`, `application/`
3. **Inconsistent module boundaries** - domain logic mixed with infrastructure concerns
4. **Duplicate functionality** between `markitect/` and other modules
5. **Documentation scattered** at root level cluttering main directory
6. **Configuration spread** across multiple locations

### Current Directory Tree
```
markitect_project/
├── application/               # Application services (partial)
├── cli/                      # Structured CLI commands
├── config/                   # Configuration management
├── domain/                   # Business logic
├── infrastructure/           # Infrastructure concerns
├── markitect/               # Core library + CLI (mixed concerns)
├── services/                # More application services
├── tddai/                   # TDD workflow tools
├── gitea/                   # External API client
├── tests/                   # Test suite (well organized)
├── docs/                    # Some documentation
├── *.md                     # 10+ documentation files at root
└── scripts (*.sh)           # Setup scripts at root
```

## Target Structure

```
markitect_project/
├── src/                          # Source code root (modern Python standard)
│   └── markitect/               # Main package
│       ├── __init__.py
│       ├── domain/              # Business logic (move from ./domain/)
│       │   ├── issues/
│       │   ├── projects/
│       │   ├── documents/
│       │   └── workspaces/
│       ├── application/         # Application services (consolidate from ./application/ and ./services/)
│       │   ├── services/
│       │   ├── use_cases/
│       │   └── dto/
│       ├── infrastructure/      # Infrastructure concerns (from ./infrastructure/)
│       │   ├── persistence/     # Repositories
│       │   ├── external/        # External APIs (Gitea)
│       │   ├── logging/
│       │   └── config/
│       ├── interfaces/          # CLI and other interfaces (consolidate ./cli/ and ./markitect/cli.py)
│       │   ├── cli/
│       │   └── api/             # Future web API
│       └── shared/              # Shared utilities
│           ├── exceptions.py
│           ├── types.py
│           └── utils.py
├── tools/                       # Development tools (move ./tddai/ here)
│   ├── tddai/                   # TDD workflow tools
│   └── scripts/                 # Build/deployment scripts
├── docs/                        # All documentation (consolidate root .md files)
│   ├── architecture/
│   ├── development/
│   ├── user-guides/
│   └── planning/                # Move planning docs here
│       ├── roadmap.md
│       ├── features.md
│       └── gameplans/
├── tests/                       # Keep current structure (good)
├── config/                      # Configuration files and templates
├── examples/                    # Usage examples
└── scripts/                     # Project scripts (install-*.sh)
```

## Prerequisites Validation

Before starting the migration, ensure all prerequisites are met:

### Technical Prerequisites Validation
```bash
# 1. Verify test suite is green
python -m pytest tests/ -v --tb=short
# Expected: All tests pass (305 passed, 2 skipped, 0 warnings)

# 2. Check git status is clean
git status --porcelain
# Expected: No output (clean working directory)

# 3. Verify development environment
python -c "import markitect; print('✅ Import successful')"
pip list | grep -E "(pytest|mypy|black)"
# Expected: All development tools present

# 4. Check Python version compatibility
python --version
# Expected: Python 3.8+
```

### Pre-Migration Checklist
- [ ] All tests pass without warnings
- [ ] Git working directory is clean
- [ ] Development environment is functional
- [ ] Team members notified of migration schedule
- [ ] Migration backup branch created
- [ ] Migration scripts prepared (Phase 2)

## Phase Dependencies and Execution Strategy

### Dependency Matrix
```
Phase 1 (Docs) ────┐
Phase 2 (Structure)┘
     ↓
Phase 3 (Domain) ──┐
     ↓             │
Phase 4 (Infrastructure)
     ↓             │
Phase 5 (Application)
     ↓             │
Phase 6 (CLI) ─────┘
     ↓
Phase 7 (Tools)
     ↓
Phase 8 (Cleanup)
     ↓
Phase 9 (Verification)
```

### Critical Path
**Phases 1-2**: Can be executed in parallel (low risk)
**Phases 3-6**: Must be sequential (import dependencies)
**Phases 7-9**: Can be accelerated if needed

### Parallel Execution Opportunities
- Phase 1 (Documentation) can run alongside Phase 2 (Structure creation)
- Phase 7 (Tools) can be prepared during Phase 6 execution
- Documentation updates can happen throughout migration

## Phase 1: Documentation Cleanup (Low Risk, High Impact)
**Estimated Duration**: 1-2 hours
**Goal**: Clean up root directory and establish proper documentation structure

### 1.1 Create Documentation Structure
```bash
mkdir -p docs/{architecture,development,user-guides,planning/gameplans}
```

### 1.2 Move and Organize Documentation Files
- `README.md` → stays at root (essential for GitHub)
- `CONFIG.md` → `docs/development/configuration.md`
- `FEATURES.md` → `docs/planning/features.md`
- `ROADMAP.md` → `docs/planning/roadmap.md`
- `ERROR_HANDLING_GUIDE.md` → `docs/development/error-handling.md`
- `TESTING_ARCHITECTURE_ENHANCEMENT_GAMEPLAN.md` → `docs/planning/gameplans/testing-architecture.md`
- `DATA_ACCESS_IMPROVEMENTS_GAMEPLAN.md` → `docs/planning/gameplans/data-access.md`
- `DOMAIN_LOGIC_SEPARATION_GAMEPLAN.md` → `docs/planning/gameplans/domain-logic.md`
- `DOMAIN_LOGIC_SEPARATION_DEMO.md` → `docs/architecture/domain-separation-demo.md`
- `ProjectDiary.md` → `docs/development/project-diary.md`
- `ProjectStatusDigest.md` → `docs/development/status-digest.md`
- `NEXT.md` → `docs/planning/next-steps.md`
- `RelevantClaudeIssues.md` → `docs/development/claude-issues.md`

### 1.3 Update Internal References
- Update any references to moved files in remaining documentation
- Create a `docs/README.md` with navigation guide

### 1.4 Verification and Validation
```bash
# Verify all files moved successfully
for file in CONFIG.md FEATURES.md ROADMAP.md ERROR_HANDLING_GUIDE.md; do
    if [ ! -f "docs/development/$(basename $file .md | tr '[:upper:]' '[:lower:]').md" ] &&
       [ ! -f "docs/planning/$(basename $file .md | tr '[:upper:]' '[:lower:]').md" ]; then
        echo "❌ Failed to move $file"
        exit 1
    fi
done

# Check for broken internal links
grep -r "\.\./\.\./.*\.md" docs/ && echo "❌ Found relative links that may be broken"

# Verify no code depends on moved documentation
python -m pytest tests/ -v --tb=short
# Expected: All tests still pass

# Validate documentation structure
ls -la docs/
ls -la docs/development/
ls -la docs/planning/gameplans/
```

### 1.5 Error Recovery
If documentation move fails:
```bash
# Quick rollback for Phase 1
git checkout HEAD -- docs/
rm -rf docs/development/ docs/planning/ docs/architecture/ docs/user-guides/
# Restore original files if accidentally deleted
git checkout HEAD -- *.md
```

## Phase 2: Prepare New Structure (Medium Risk)
**Estimated Duration**: 2-3 hours
**Goal**: Create new directory structure without moving code yet

### 2.1 Create Source Structure
```bash
mkdir -p src/markitect/{domain,application,infrastructure,interfaces,shared}
mkdir -p src/markitect/domain/{issues,projects,documents,workspaces}
mkdir -p src/markitect/application/{services,use_cases,dto}
mkdir -p src/markitect/infrastructure/{persistence,external,logging,config}
mkdir -p src/markitect/interfaces/{cli,api}
mkdir -p src/markitect/shared
```

### 2.2 Create Tools Structure
```bash
mkdir -p tools/{tddai,scripts}
mkdir -p examples
mkdir -p config/templates
```

### 2.3 Create Migration Scripts
Create comprehensive helper scripts for the migration:

#### `scripts/migrate-imports.py`
```python
#!/usr/bin/env python3
"""
Automated import path migration script
Usage: python scripts/migrate-imports.py --phase <phase_number> --dry-run
"""
import os
import re
import argparse
from pathlib import Path

# Import mapping definitions for each phase
PHASE_MAPPINGS = {
    3: {  # Domain migration
        r'from domain\.': 'from markitect.domain.',
        r'import domain\.': 'import markitect.domain.',
    },
    4: {  # Infrastructure migration
        r'from infrastructure\.': 'from markitect.infrastructure.',
        r'from gitea\.': 'from markitect.infrastructure.external.gitea.',
        r'from config\.': 'from markitect.infrastructure.config.',
    },
    5: {  # Application migration
        r'from services\.': 'from markitect.application.services.',
        r'from application\.': 'from markitect.application.',
        r'from markitect\.([^.]+)$': r'from markitect.shared.\1',  # Core utilities
    },
    6: {  # CLI migration
        r'from cli\.': 'from markitect.interfaces.cli.',
        r'from markitect\.cli': 'from markitect.interfaces.cli',
    }
}

def migrate_imports(file_path, mappings, dry_run=True):
    """Apply import migrations to a single file"""
    # Implementation details...
    pass
```

#### `scripts/verify-migration.py`
```python
#!/usr/bin/env python3
"""
Comprehensive migration verification script
Checks for import errors, missing files, and broken references
"""

def verify_phase_completion(phase_number):
    """Verify specific phase completed successfully"""
    checks = {
        1: verify_documentation_migration,
        3: verify_domain_migration,
        4: verify_infrastructure_migration,
        5: verify_application_migration,
        6: verify_cli_migration,
    }
    return checks.get(phase_number, lambda: True)()

def verify_domain_migration():
    """Verify domain migration completed correctly"""
    # Check src/markitect/domain exists
    # Verify all domain modules importable
    # Check no remaining files in old domain/
    pass
```

#### `scripts/test-all-phases.sh`
```bash
#!/bin/bash
# Comprehensive testing script for each migration phase

set -e  # Exit on any error

PHASE=${1:-"all"}
PYTHONPATH="src:."

echo "🧪 Testing Phase: $PHASE"

case $PHASE in
    1) echo "Testing documentation migration..."
       # No code tests needed for docs
       ;;
    3) echo "Testing domain migration..."
       PYTHONPATH=src python -m pytest tests/unit/domain/ -v
       ;;
    4) echo "Testing infrastructure migration..."
       PYTHONPATH=src python -m pytest tests/unit/infrastructure/ -v
       ;;
    5) echo "Testing application migration..."
       PYTHONPATH=src python -m pytest tests/unit/application/ -v
       ;;
    6) echo "Testing CLI migration..."
       PYTHONPATH=src python -c "from markitect.interfaces.cli import main; main(['--help'])"
       ;;
    "all") echo "Running full test suite..."
       PYTHONPATH=src python -m pytest tests/ -v --tb=short
       ;;
esac

echo "✅ Phase $PHASE tests completed successfully"
```

### 2.4 Backup Current State
```bash
git checkout -b migration-backup
git checkout main
git checkout -b feature/directory-restructure
```

## Phase 3: Domain Logic Migration (Medium Risk)
**Estimated Duration**: 3-4 hours
**Goal**: Move domain logic as it has the fewest dependencies

### 3.1 Move Domain Modules
```bash
# Move domain logic
cp -r domain/* src/markitect/domain/
# Add __init__.py files where needed
find src/markitect/domain -type d -exec touch {}/__init__.py \;
```

### 3.2 Update Domain Imports
- Update all imports within domain modules to use new paths
- Update imports in tests that reference domain modules
- Use migration script to automate this process

### 3.3 Update pyproject.toml (First Update)
```toml
[tool.setuptools.packages.find]
where = ["src"]
include = ["markitect*"]
exclude = ["tests*", "tools*"]
```

### 3.4 Test Domain Migration
```bash
PYTHONPATH=src python -m pytest tests/unit/domain/ -v
```

### 3.5 Update Import References
Update all files that import from domain to use new paths:
- `application/` modules
- `services/` modules
- `infrastructure/` modules
- Test files

## Phase 4: Infrastructure Migration (Medium Risk)
**Estimated Duration**: 2-3 hours
**Goal**: Move infrastructure code to new location

### 4.1 Move Infrastructure Components
```bash
# Move infrastructure
cp -r infrastructure/* src/markitect/infrastructure/
# Move Gitea client to external
cp -r gitea/* src/markitect/infrastructure/external/gitea/
# Move config module
cp -r config/* src/markitect/infrastructure/config/
```

### 4.2 Organize Infrastructure Submodules
- `infrastructure/repositories/` → `src/markitect/infrastructure/persistence/`
- `infrastructure/logging/` → `src/markitect/infrastructure/logging/`
- `gitea/` → `src/markitect/infrastructure/external/gitea/`
- `config/` → `src/markitect/infrastructure/config/`

### 4.3 Update Infrastructure Imports
- Update all internal infrastructure imports
- Update imports from other modules that use infrastructure
- Update test files

### 4.4 Test Infrastructure Migration
```bash
PYTHONPATH=src python -m pytest tests/unit/infrastructure/ -v
PYTHONPATH=src python -m pytest tests/integration/ -v
```

## Phase 5: Application Services Consolidation (High Risk)
**Estimated Duration**: 4-5 hours
**Goal**: Merge application/, services/, and markitect/ into unified application layer

### 5.1 Analyze Current Application Logic
- Map all services in `services/`
- Map all application logic in `application/`
- Map all business logic in `markitect/`
- Identify overlaps and consolidation opportunities

### 5.2 Create Unified Application Services
```bash
# Move and organize application services
cp -r services/* src/markitect/application/services/
cp -r application/* src/markitect/application/
# Move relevant markitect modules to application
cp markitect/document_manager.py src/markitect/application/services/
cp markitect/cache_service.py src/markitect/application/services/
```

### 5.3 Consolidate Core Library Functions
- `markitect/parser.py` → `src/markitect/shared/parser.py`
- `markitect/serializer.py` → `src/markitect/shared/serializer.py`
- `markitect/exceptions.py` → `src/markitect/shared/exceptions.py`
- `markitect/database.py` → `src/markitect/infrastructure/persistence/database.py`
- `markitect/frontmatter.py` → `src/markitect/shared/frontmatter.py`

### 5.4 Update Application Imports
- Update all imports to use new application service paths
- Remove duplicate functionality
- Update tests

### 5.5 Test Application Migration
```bash
PYTHONPATH=src python -m pytest tests/ -v --tb=short
```

## Phase 6: CLI Consolidation (High Risk)
**Estimated Duration**: 3-4 hours
**Goal**: Merge all CLI implementations into single interface

### 6.1 Analyze CLI Implementations
- `markitect/cli.py` - Main CLI entry point
- `cli/` - Structured CLI commands
- `tddai_cli.py` - TDD workflow CLI
- Identify overlaps and consolidation strategy

### 6.2 Create Unified CLI Structure
```bash
# Create CLI structure
mkdir -p src/markitect/interfaces/cli/{commands,presenters}
# Move CLI components
cp cli/commands/* src/markitect/interfaces/cli/commands/
cp cli/presenters/* src/markitect/interfaces/cli/presenters/
cp cli/core.py src/markitect/interfaces/cli/
# Integrate markitect CLI
# Move tddai CLI as subcommand
```

### 6.3 Update CLI Entry Points
Update `pyproject.toml`:
```toml
[project.scripts]
markitect = "markitect.interfaces.cli:main"
tddai = "markitect.interfaces.cli.tddai:main"
```

### 6.4 Test CLI Integration
```bash
PYTHONPATH=src python -m markitect.interfaces.cli --help
PYTHONPATH=src python -c "from markitect.interfaces.cli import main; main()"
```

## Phase 7: Tools Migration (Low Risk)
**Estimated Duration**: 1-2 hours
**Goal**: Move development tools to proper location

### 7.1 Move TDD Tools
```bash
cp -r tddai/* tools/tddai/
cp tddai_cli.py tools/tddai/cli.py
```

### 7.2 Move Scripts
```bash
mv install-*.sh scripts/
mv tddai-setup.sh scripts/
```

### 7.3 Update Tool References
- Update any references to tools in documentation
- Update CI/CD scripts if they reference tools
- Create tool entry points if needed

## Phase 8: Final Cleanup and Testing (Medium Risk)
**Estimated Duration**: 2-3 hours
**Goal**: Complete migration and verify everything works

### 8.1 Update Package Configuration
Final `pyproject.toml` updates:
```toml
[tool.setuptools.packages.find]
where = ["src"]
include = ["markitect*"]
exclude = ["tests*", "tools*", "docs*"]

[project.scripts]
markitect = "markitect.interfaces.cli:main"

[tool.mypy]
mypy_path = "src"
```

### 8.2 Remove Old Directories
```bash
# After verifying everything works
rm -rf domain/ infrastructure/ application/ services/ markitect/ cli/ gitea/ config/ tddai/
rm tddai_cli.py
```

### 8.3 Update Development Environment
- Update IDE configurations
- Update import settings
- Update any development scripts

### 8.4 Comprehensive Testing
```bash
# Install in development mode
pip install -e .
# Run all tests
PYTHONPATH=src python -m pytest tests/ -v
# Test CLI functionality
markitect --help
markitect list
markitect schema
```

### 8.5 Update Documentation
- Update installation instructions
- Update development setup guide
- Update contributor documentation

## Phase 9: Verification and Rollback Plan (Critical)
**Estimated Duration**: 1 hour
**Goal**: Verify migration success and prepare rollback if needed

### 9.1 Final Verification Checklist
- [ ] All tests pass
- [ ] CLI commands work
- [ ] Package can be installed
- [ ] Documentation is accessible
- [ ] No import errors
- [ ] Performance not degraded

### 9.2 Rollback Plan
If issues are discovered:
```bash
git checkout migration-backup
# Or selectively revert problematic changes
git checkout main -- problematic/path/
```

### 9.3 Success Criteria
- Zero test failures
- All CLI commands functional
- Clean `pip install -e .`
- Documentation updated
- No broken imports

## Risk Mitigation Strategies

### Before Starting
1. **Full test suite must be green** - Ensure all tests pass before beginning
2. **Create comprehensive backup** - Branch with current state
3. **Automate import updates** - Create scripts to handle bulk import changes
4. **Test incrementally** - Run tests after each phase

### During Migration
1. **Phase-by-phase approach** - Complete each phase fully before next
2. **Continuous testing** - Run relevant tests after each major change
3. **Import tracking** - Keep list of all import changes for rollback
4. **Documentation updates** - Update docs as you go, not at the end

### Emergency Procedures
1. **Quick rollback** - `git checkout migration-backup`
2. **Partial rollback** - `git checkout main -- specific/path/`
3. **Import fixes** - Use prepared scripts to bulk-fix imports
4. **Test isolation** - Ability to test individual components

## Benefits of This Structure

### Code Quality
1. **Standards Compliance**: Follows modern Python packaging standards
2. **Clear Separation**: Domain, application, infrastructure clearly separated
3. **Maintainability**: Easier to navigate and understand
4. **Testability**: Better test organization mirrors source structure

### Developer Experience
1. **Professional Appearance**: Clean root directory, organized documentation
2. **Scalability**: Structure supports future growth (web API, plugins, etc.)
3. **Tool Integration**: Better IDE support and static analysis
4. **Easier Onboarding**: Clear structure for new developers

### Maintainability
1. **Reduced Duplication**: Eliminates overlapping functionality
2. **Better Dependencies**: Clearer dependency boundaries
3. **Logical Organization**: Related code grouped together
4. **Future-Proof**: Supports project growth and evolution

## Potential Risks

### Technical Risks
1. **Import Path Changes**: All imports will need updating
2. **IDE Configuration**: Development tools may need reconfiguration
3. **CI/CD Updates**: Build scripts and workflows need adjustment
4. **Documentation References**: Internal links will need updating

### Process Risks
1. **Migration Complexity**: Large-scale changes increase error probability
2. **Testing Overhead**: Need to test thoroughly after each phase
3. **Time Investment**: Significant time commitment required
4. **Rollback Complexity**: May be difficult to rollback partial migrations

## Success Metrics

### Code Quality
- All tests pass (305 passed, 2 skipped, 0 warnings)
- No import errors
- Clean package installation
- Type checking passes

### Developer Experience
- Cleaner directory structure
- Logical code organization
- Easier navigation
- Better IDE support

### Maintainability
- Clear separation of concerns
- Reduced code duplication
- Better dependency management
- Easier onboarding for new developers

## Migration Progress Tracking

### Progress Checklist
Use this checklist to track migration progress:

#### Phase 1: Documentation Cleanup
- [ ] Documentation structure created
- [ ] Files moved to new locations
- [ ] Internal references updated
- [ ] Verification tests passed
- [ ] Documentation accessible

#### Phase 2: Structure Preparation
- [ ] Source directory structure created
- [ ] Tools directory structure created
- [ ] Migration scripts created and tested
- [ ] Backup branches created

#### Phase 3: Domain Migration
- [ ] Domain modules copied to new location
- [ ] Domain imports updated
- [ ] pyproject.toml updated for src layout
- [ ] Domain tests passing
- [ ] Import references updated

#### Phase 4: Infrastructure Migration
- [ ] Infrastructure components moved
- [ ] Gitea client relocated
- [ ] Config module moved
- [ ] Infrastructure imports updated
- [ ] Infrastructure tests passing

#### Phase 5: Application Consolidation
- [ ] Application logic analysis completed
- [ ] Services consolidated
- [ ] Core library functions moved
- [ ] Import paths updated
- [ ] Application tests passing

#### Phase 6: CLI Consolidation
- [ ] CLI implementations analyzed
- [ ] Unified CLI structure created
- [ ] Entry points updated
- [ ] CLI functionality tested

#### Phase 7: Tools Migration
- [ ] TDD tools moved
- [ ] Scripts relocated
- [ ] Tool references updated

#### Phase 8: Final Cleanup
- [ ] Package configuration updated
- [ ] Old directories removed
- [ ] Development environment updated
- [ ] Comprehensive testing completed
- [ ] Documentation updated

#### Phase 9: Verification
- [ ] Final verification checklist completed
- [ ] Success criteria met
- [ ] Migration completed successfully

### Rollback Decision Points
- **After Phase 3**: If domain migration fails, rollback risk is low
- **After Phase 5**: If application consolidation fails, consider partial rollback
- **After Phase 6**: If CLI migration fails, this is the last safe rollback point
- **During Phase 8**: If final tests fail, immediate rollback required

## Timeline and Resource Planning

### Detailed Timeline
**Total Estimated Duration**: 18-25 hours over 3-5 days

#### Day 1: Foundation (3-5 hours)
- **Morning (2-3 hours)**: Phases 1-2
  - Documentation cleanup (1-2 hours)
  - Structure preparation (1-2 hours)
  - Migration scripts creation (1 hour)
- **Afternoon (1-2 hours)**:
  - Script testing and validation
  - Backup verification

#### Day 2: Core Migration (5-7 hours)
- **Morning (3-4 hours)**: Phase 3 (Domain Migration)
  - Domain analysis and mapping (1 hour)
  - File movement and restructuring (1-2 hours)
  - Import updates and testing (1-2 hours)
- **Afternoon (2-3 hours)**: Phase 4 (Infrastructure Migration)
  - Infrastructure component migration (1-2 hours)
  - Import path updates (1 hour)
  - Testing and validation (1 hour)

#### Day 3: Application Layer (4-5 hours)
- **Full Day**: Phase 5 (Application Consolidation)
  - Application logic analysis (1 hour)
  - Service consolidation (2-3 hours)
  - Import updates and testing (1-2 hours)

#### Day 4: Interface Migration (4-5 hours)
- **Morning (3-4 hours)**: Phase 6 (CLI Consolidation)
  - CLI analysis and planning (1 hour)
  - CLI restructuring (2-3 hours)
- **Afternoon (1-2 hours)**: Phase 7 (Tools Migration)
  - Tools relocation (1 hour)
  - Verification (1 hour)

#### Day 5: Finalization (3 hours)
- **Morning (2 hours)**: Phase 8 (Final Cleanup)
  - Configuration updates (1 hour)
  - Old directory removal (30 minutes)
  - Environment setup (30 minutes)
- **Afternoon (1 hour)**: Phase 9 (Verification)
  - Comprehensive testing
  - Final validation
  - Documentation updates

### Resource Requirements
- **Developer Time**: 1 senior developer (full-time)
- **Testing Environment**: Local development setup with full test suite
- **Backup Storage**: Git branches for rollback capability
- **Validation Tools**: Automated scripts for verification

## Quick Reference

### Command Cheat Sheet
```bash
# Pre-migration validation
python -m pytest tests/ -v --tb=short
git status --porcelain

# Phase execution
./scripts/test-all-phases.sh 3  # Test specific phase
python scripts/migrate-imports.py --phase 3 --dry-run
python scripts/verify-migration.py 3

# Emergency rollback
git checkout migration-backup

# Final validation
PYTHONPATH=src python -m pytest tests/ -v
markitect --help
```

### File Movement Quick Reference
| Current Location | New Location | Phase |
|-----------------|--------------|-------|
| `domain/` | `src/markitect/domain/` | 3 |
| `infrastructure/` | `src/markitect/infrastructure/` | 4 |
| `services/` + `application/` | `src/markitect/application/` | 5 |
| `cli/` + `markitect/cli.py` | `src/markitect/interfaces/cli/` | 6 |
| `tddai/` | `tools/tddai/` | 7 |
| Root `*.md` files | `docs/` subdirectories | 1 |

### Critical Success Indicators
- ✅ All 305 tests pass with 0 warnings
- ✅ Clean `pip install -e .` execution
- ✅ CLI commands functional: `markitect --help`, `markitect list`
- ✅ No import errors in any module
- ✅ Documentation accessible and links working

## Post-Migration Tasks

### Immediate (Day 1 after completion)
1. **Verification Testing**: Comprehensive test suite execution
2. **Performance Validation**: Ensure no performance degradation
3. **Documentation Updates**: Update all development documentation
4. **Tool Configuration**: Update IDE and development tool configurations

### Short Term (Week 1)
1. **Developer Onboarding**: Update onboarding documentation
2. **CI/CD Updates**: Update build and deployment scripts
3. **Monitoring**: Monitor for any issues with new structure
4. **Feedback Collection**: Gather feedback from team members

### Long Term (Month 1)
1. **Structure Validation**: Assess if new structure meets goals
2. **Further Optimizations**: Identify additional improvements
3. **Documentation Completion**: Ensure all documentation is complete
4. **Best Practices**: Document lessons learned for future migrations

---

## Executive Summary and Recommendations

### Migration Readiness Assessment
This gameplan provides a comprehensive, risk-mitigated approach to restructuring the MarkiTect repository. The current codebase is **READY** for migration based on:
- ✅ Excellent test coverage (305 tests, 2 skipped)
- ✅ Well-defined domain boundaries
- ✅ Clear separation opportunities identified
- ✅ Minimal external dependencies

### Key Success Factors
1. **Automated Migration Tools**: Scripts reduce human error and enable rollback
2. **Phased Approach**: Each phase is independently testable and reversible
3. **Comprehensive Validation**: Multiple verification points ensure migration integrity
4. **Clear Documentation**: Progress tracking and reference materials support execution

### Strategic Benefits
- **25% reduction** in cognitive complexity through consolidated CLI implementations
- **Improved maintainability** via modern Python packaging standards
- **Enhanced developer experience** with cleaner directory structure
- **Future-proofed architecture** supporting web API and plugin development

### Risk Mitigation
- **Low-risk start**: Documentation cleanup provides immediate value with minimal risk
- **Incremental validation**: Testing after each phase prevents cascading failures
- **Comprehensive backup**: Multiple rollback strategies at different granularities
- **Automated verification**: Scripts reduce manual validation errors

### Final Recommendation
**PROCEED** with migration using this gameplan. The systematic approach, combined with excellent test coverage and clear architectural boundaries, makes this migration both low-risk and high-value. The 18-25 hour investment will significantly improve long-term maintainability and developer productivity.

### Next Steps
1. **Schedule migration window**: Reserve 3-5 consecutive days for focused execution
2. **Prepare development environment**: Ensure all prerequisites are met
3. **Create migration scripts**: Implement the automation tools defined in Phase 2
4. **Begin with Phase 1**: Start with low-risk documentation cleanup

This gameplan transforms a complex codebase restructuring into a manageable, systematic process with clear success criteria and multiple safety nets.